Developing Smart Tag DLLs

This content is no longer actively maintained. It is provided as is, for anyone who may still be using these technologies, with no warranties or claims of accuracy with regard to the most recent product version or service release.

 

Paul Cornell
Microsoft Corporation

April 2001

Applies to:
   Microsoft® Office XP

This article assumes you are familiar with Microsoft® Visual Basic®, the Component Object Model (COM), and dynamic-link libraries (DLLs).

Summary: Describes how to create, test, and deploy smart tag dynamic-link libraries in Microsoft Office XP by using Microsoft Visual Basic and the Microsoft Smart Tags 1.0 type library. (13 printed pages).

Download ODC_SmartTags.exe.

Contents

Introduction
Exploring the Smart Tags Interfaces
Developing Your First Smart Tag DLL    Creating the DLL Project    Implementing the ISmartTagRecognizer Interface    Implementing the ISmartTagAction Interface
Compiling and Registering the Smart Tag DLL
Testing the Smart Tag DLL
Conclusion

Introduction

Every text-based communication contains letters, numbers, and symbols, but the real power of communication comes within its context. For example, if you see the letters "MSFT" in a newspaper, you would probably recognize this as the stock ticker symbol for the Microsoft Corporation. That's because you know what stock ticker symbols look like. However, your computer just looks at MSFT as a string of letters.

The new smart tags feature in Microsoft® Office XP is a powerful tool for adding this context to your Office documents, or build new contexts of your own. For instance, when someone enters "555-555-1212" in a document, a smart tag recognizer could recognize this as a phone number smart tag, and provide the option to add a new contact record in Microsoft® Outlook® and fill in the business field of the new contact record with that phone number. But a manufacturing company that uses the same numbering scheme for part numbers could change the context; for example, the company could provide the option to cross-reference the part number against inventory levels stored in a Microsoft Access 2002 database. Smart tags are currently available for Microsoft Word 2002 and Microsoft Excel 2002, Microsoft Outlook 2002 (when Word 2002 is used as your e-mail editor) and Internet Explorer. Users must have Office XP installed on their computers to be able to view and use smart tags in the documents you create. Figure 1 below provides a picture of what a smart tag looks like.

Figure 1. A smart tag in action

You can create a smart tag recognizer by using Extensible Markup Language (XML) in association with the smart tag XML list schema, or by using Hypertext Markup Language (HTML) inside a Web page, but these solutions aren't very extensible. If you want to automate programmatic access to smart tags, your best choice is to create a dynamic-link library (DLL).

To develop a smart tag DLL, in addition to Office XP, you will need a Component Object Model (COM) development system such as Microsoft Visual Basic 6.0 Professional Edition or later because the Microsoft Visual Basic for Applications development environment in Office does not provide the ability to create DLLs.

This article explores how to create smart tag DLLs through code. By following the code samples and steps below, you can develop, compile, register, and test your first smart tag DLL.

For more information about creating a smart tag recognizer by using XML or HTML, as well as how to develop smart tag DLLs, see the Smart Tags Software Development Kit (SDK), which will be available through MSDN after Office XP is released.

Exploring the Smart Tags Interfaces

To create smart tags, Office XP provides the Microsoft Smart Tags 1.0 type library, which consists of a collection of properties and methods grouped into interfaces. An interface is a group of properties and methods that act as a type of blueprint, saving trial and error during development.

The two main interfaces in the Microsoft Smart Tags 1.0 type library are the ISmartTagRecognizer interface, which recognizes character strings as smart-tag actionable by marking recognized strings with a dotted purple underline and displaying the Smart Tag Actions button, and the ISmartTagAction interface, which both provides a list of actions when the Smart Tag Actions button is clicked and carries out the selected action from the list.

Table 1 below lists the properties and methods of the ISmartTagRecognizer interface, and Table 2 below lists the properties and methods of the ISmartTagAction interface. When you create a smart tag DLL, you'll need to add implementation code to all 18 of these properties and methods together as specified by these two interfaces. We'll explore these members more in the code samples that follow.

Table 1. ISmartTagRecognizer interface members

Member	Description
Desc property	A description of the smart tag recognizer.
Name property	A name for the recognizer (the name appears in the Smart Tags tab (Tools menu, AutoCorrect Options dialog box) in both Word and Excel.
ProgID property	The unique identifier (programmatic ID) for the recognizer's class.
Recognize method	The method that recognizes character strings as smart-tag actionable.
SmartTagCount property	The number of smart tag types that this recognizer recognizes.
SmartTagDownloadURL property	The URL that is navigated to if the More Smart Tags button (Tools menu, AutoCorrect Options dialog box, Smart Tags tab) is clicked.
SmartTagName property	The unique identifiers for smart tag types that the recognizer supports.

Table 2. ISmartTagAction interface members

Member	Description
Desc property	A description of the smart tag action.
InvokeVerb method	The action that occurs when an item is clicked on the Smart Tag Actions menu.
Name property	A title for the action.
ProgID property	The unique identifier (programmatic ID) of the action's class.
SmartTagCaption property	The caption that will be displayed at the top of the Smart Tag Actions menu.
SmartTagCount property	The number of smart tag types the corresponding recognizer recognizes.
SmartTagName property	The types of smart tag actions.
VerbCaptionFromID property	The captions for the available actions in the Smart Tag Actions menu.
VerbCount property	For a given smart tag type, the property that determines how many actions are supported.
VerbID property	The property that returns a unique ID (used internally within the application) within the smart tag. This mechanism is supplied so that smart tag DLLs can mix and match smart tag actions for the various smart tag types they support.
VerbNameFromID property	The property that returns a name (used internally within the application) to represent the smart tag action. For example, for the smart tag action string "View Microsoft Web site", this property might return something like "viewMSWebsite".

Now that you know how smart tag interfaces work, you can code your first smart tag DLL.

Developing Your First Smart Tag DLL

In this smart tag solution, Word, Excel, Outlook (with Word as your e-mail editor), or Internet Explorer (when a Word or Excel document is saved as a Web page) will display the Smart Tag Actions button whenever a user types the words or rests the mouse pointer on the words "Access", "Excel", "Office", "Outlook", "PowerPoint", or "Word" in the document. When the Smart Tag Actions button is clicked, a menu will appear that allows users to go to select Microsoft Web sites about Office applications. Your finished solution will look like the one in Figure 2 below.

Figure 2. Your first smart tag

Creating the DLL Project

For this project, we'll be using Visual Basic 6.0. To get started, you create and set up the DLL project that will contain the code for your custom smart tag DLL. For this project to work properly, you must have Visual Basic 6.0 Professional Edition or later and Office XP installed on the same development computer. You can skip most of these steps by downloading the sample file; a link to the sample file is provided at the beginning of this article. The code in the sample file is thoroughly commented, so if you don't understand some of the code described below, refer to the sample file.

To create and set up the DLL project

1. In Visual Basic 6.0, in the New Project dialog box, double-click ActiveX DLL.
2. On the Project menu, click Project1 Properties.
3. In the Project Name box, type MicrosoftWebSite. Then click OK.
4. In the Properties window, in the (Name) box, type over Class1 and change it to SmartTagRecognizer.
5. On the Project menu, click References, select Microsoft Smart Tags 1.0 Type Library, and then click OK.
6. In the General Declarations section of the SmartTagRecognizer class code, type the following: Implements ISmartTagRecognizer
7. On the Projectmenu, clickAdd Class Module. Then click Open.
8. In the Properties window, in the (Name) box, type over Class1 and change it to SmartTagAction.
9. In the General Declarations section of the SmartTagAction class code, type the following: Implements ISmartTagAction
10. On the Projectmenu, clickMicrosoftWebSite Properties. On the Componenttab, clickProject Compatibility. Then click OK.
11. Save your work.

Now that you've set up the DLL project, let's implement the ISmartTagRecognizer interface.

Implementing the ISmartTagRecognizer Interface

To implement the ISmartTagRecognizer interface, follow these four steps:

1. Provide a unique ID, title, and description for the smart tag recognizer by adding code to the ProgId, Name, and Desc properties in your SmartTagRecognizer class as follows:

   Private Property Get ISmartTagRecognizer_ProgId() _
           As String
   
       ISmartTagRecognizer_ProgId = _
           "MicrosoftWebSite.SmartTagRecognizer"
   
   End Property
   
   Private Property Get ISmartTagRecognizer_Name _
           (ByVal LocaleID As Long) As String
   
       ISmartTagRecognizer_Name = _
           "Microsoft Web Sites Smart Tag"
   
   End Property
   
   Private Property Get ISmartTagRecognizer_Desc _
           (ByVal LocaleID As Long) As String
   
       ISmartTagRecognizer_Desc = _
           "Directs users to related Microsoft Web sites"
   
   End Property
   

2. Provide the number of smart tag types, the list of smart tag action types, and the additional smart tags download location of the recognizer by adding code to the SmartTagCount, SmartTagName, and SmartTagDownload properties in your SmartTagRecognizer class as follows:

   Private Property Get ISmartTagRecognizer_SmartTagCount() _
           As Long
   
       ISmartTagRecognizer_SmartTagCount = 1
   
   End Property
   
   Private Property Get ISmartTagRecognizer_SmartTagName _
           (ByVal SmartTagID As Long) As String
   
       If SmartTagID = 1 Then
           ISmartTagRecognizer_SmartTagName = _
               "my-company-com#mswebsite"
       End If
   
   End Property
   
   Private Property Get ISmartTagRecognizer_SmartTagDownloadURL _
           (ByVal SmartTagID As Long) As String
   
       ISmartTagRecognizer_SmartTagDownloadURL = Null
   
   End Property
   

3. Provide a list of items to recognize by adding code to your SmartTagRecognizer class's General Declarations section and Class_Initialize routine as follows:

   Dim garrTerms(6) As String   
   Dim gintNumTerms As Integer  
   
   Private Sub Class_Initialize()
   
       garrTerms(1) = "office"
       garrTerms(2) = "access"
       garrTerms(3) = "excel"
       garrTerms(4) = "outlook"
       garrTerms(5) = "powerpoint"
       garrTerms(6) = "word"
       gintNumTerms = 6
   
   End Sub
   

4. Search for smart-tag actionable character strings every time text is entered in a Word, Excel, or Outlook document (when Word is used as the e-mail editor) by adding code to the Recognize method of your SmartTagRecognizer class as follows:

   Private Sub ISmartTagRecognizer_Recognize _
           (ByVal Text As String, _
           ByVal DataType As SmartTagLib.IF_TYPE, _
           ByVal LocaleID As Long, _
           ByVal RecognizerSite As _
               SmartTagLib.ISmartTagRecognizerSite)
   
       Dim intLoop As Integer
       Dim intIndex As Integer
       Dim intTermLen As Integer
       Dim stlPropertyBag As SmartTagLib.IsmartTagProperties
   
       Text = LCase(String:=Text)
   
       For intLoop = 1 To gintNumTerms
           intIndex = InStr(Text, garrTerms(intLoop))
           intTermLen = Len(garrTerms(intLoop))
           Do While intIndex > 0
               Set stlPropertyBag = _
                   RecognizerSite.GetNewPropertyBag
               RecognizerSite.CommitSmartTag _
                   "my-company-com#mswebsite", intIndex, _
                   intTermLen, stlPropertyBag
               intIndex = InStr(intIndex + intTermLen, _
                   Text, garrTerms(intLoop))
           Loop
   
       Next intLoop
   
   End Sub
   

Now that we're done implementing the ISmartTagRecognizer interface, let's implement the ISmartTagAction interface.

Implementing the ISmartTagAction Interface

To implement the ISmartTagAction interface, follow these four steps:

1. Provide a unique ID, title, and description for your smart tag action DLL by adding code to the ProgId, Name, and Desc properties in your SmartTagAction class as follows:

   Private Property Get ISmartTagAction_ProgId() As String
   
       ISmartTagAction_ProgId = _
           "MicrosoftWebSite.SmartTagAction"
   
   End Property
   
   Private Property Get ISmartTagAction_Name _
           (ByVal LocaleID As Long) As String
   
       ISmartTagAction_Name = "Microsoft Web site actions"
   
   End Property
   
   Private Property Get ISmartTagAction_Desc _
           (ByVal LocaleID As Long) As String
   
       ISmartTagAction_Desc = _
           "Provides actions for certain Microsoft product names"
   
   End Property
   

2. Inform the corresponding smart tag recognizer of the number, names, and captions of the matching tag types by adding code to the SmartTagCount, SmartTagName, and SmartTagCaption properties in your SmartTagAction class as follows:

   Private Property Get ISmartTagAction_SmartTagCount() _
           As Long
   
       ISmartTagAction_SmartTagCount = 1
   
   End Property
   
   Private Property Get ISmartTagAction_SmartTagName _
           (ByVal SmartTagID As Long) As String
   
       If SmartTagID = 1 Then
           ISmartTagAction_SmartTagName = _
               "my-company-com#mswebsite"
       End If
   
   End Property
   
   Private Property Get ISmartTagAction_SmartTagCaption _
           (ByVal SmartTagID As Long, _
           ByVal LocaleID As Long) _
           As String
   
       ISmartTagAction_SmartTagCaption = _
           "Selected Microsoft Web Sites"
   
   End Property
   

3. Inform the corresponding smart tag recognizer of the number, names, and IDs of the supported smart tag actions by adding code to the VerbCount, VerbID, VerbCaptionFromID, and VerbNameFromID properties in your SmartTagAction class as follows:

   Private Property Get ISmartTagAction_VerbCount _
           (ByVal SmartTagName As String) As Long
   
       If SmartTagName = "my-company-com#mswebsite" Then
           ISmartTagAction_VerbCount = 6
       End If
   
   End Property
   
   Private Property Get ISmartTagAction_VerbID _
           (ByVal SmartTagName As String, _
           ByVal VerbIndex As Long) _
           As Long
   
       ISmartTagAction_VerbID = VerbIndex
   
   End Property
   
   Private Property Get ISmartTagAction_VerbCaptionFromID _
           (ByVal VerbID As Long, _
           ByVal ApplicationName As String, _
           ByVal LocaleID As Long) _
           As String
   
       Select Case VerbID
   
           Case 1
               ISmartTagAction_VerbCaptionFromID = _
                   "Microsoft Office"
           Case 2
               ISmartTagAction_VerbCaptionFromID = _
                   "Microsoft Access"
           Case 3
               ISmartTagAction_VerbCaptionFromID = _
                   "Microsoft Excel"
           Case 4
               ISmartTagAction_VerbCaptionFromID = _
                   "Microsoft Outlook"
           Case 5
               ISmartTagAction_VerbCaptionFromID = _
                   "Microsoft PowerPoint"
           Case 6
               ISmartTagAction_VerbCaptionFromID = _
                   "Microsoft Word"
       End Select
   
   End Property
   
   Private Property Get ISmartTagAction_VerbNameFromID _
           (ByVal VerbID As Long) As String
   
       Select Case VerbID
           Case 1
               ISmartTagAction_VerbNameFromID = "Office"
           Case 2
               ISmartTagAction_VerbNameFromID = "Access"
           Case 3
               ISmartTagAction_VerbNameFromID = "Excel"
           Case 4
               ISmartTagAction_VerbNameFromID = "Outlook"
           Case 5
               ISmartTagAction_VerbNameFromID = "PowerPoint"
           Case 6
               ISmartTagAction_VerbNameFromID = "Word"
       End Select
   
   End Property
   

4. Display a list of smart tag actions every time the corresponding Smart Tag Options button is clicked by adding code to the InvokeVerb method in your SmartTagAction class as follows:

   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)
   
       Dim ieInternetExplorer As Variant
   
       Set ieInternetExplorer = _
           CreateObject("InternetExplorer.Application")
   
       With ieInternetExplorer
           Select Case VerbID
               Case 1
                   .Navigate2 "www.microsoft.com/office"
               Case 2
                   .Navigate2 "www.microsoft.com/access"
               Case 3
                   .Navigate2 "www.microsoft.com/excel"
               Case 4
                   .Navigate2 "www.microsoft.com/outlook"
               Case 5
                   .Navigate2 "www.microsoft.com/powerpoint"
               Case 6
                   .Navigate2 "www.microsoft.com/word"
           End Select
   
           .Visible = True
       End With
   
   End Sub
   

Now that you're done coding, you can compile and register the smart tag DLL on your computer, and then make sure it works properly.

Compiling and Registering the Smart Tag DLL

To compile your smart tag DLL, in Visual Basic 6.0, on the File menu, click Make MicrosoftWebSite.dll. To register your smart tag DLL, you must manipulate your computer's registry through the following subkeys:

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

In each of these subkeys, you will need to create a new subkey with a name matching the unique identifiers selected earlier. For example, MicrosoftWebSite.SmartTagRecognizer would be the name of the smart tag recognizer subkey, and MicrosoftWebSite.SmartTagAction would be the name of the smart tag action subkey.

Because making manual changes to computer registries are not recommended, you should consider using a tool such as the Microsoft® Visual Studio® Installer to create a registration package. This tool simplifies the creation of setup programs for distribution to multiple desktops as well. More information about downloading and using the Visual Studio Installer is available on the Visual Studio Web site. A helpful tutorial is also available in the Smart Tags SDK that shows you how to create a smart tag registration package by using the Visual Studio Installer, as well as registering subkeys manually for testing purposes.

After you've registered your smart tag DLL, you're ready to test the DLL.

Testing the Smart Tag DLL

To test your smart tag DLL:

1. Start Word 2002 and type PowerPoint.
2. Press the SPACEBAR or ENTER key to activate the smart tag recognizer, which will underline the word "PowerPoint" with purple dots.
3. Rest your mouse pointer on these purple dots, and the Smart Tag Actions button will appear.
4. Rest your mouse pointer on the Smart Tag Actions button, and then, to activate the actions menu, click the arrow.
5. To start Internet Explorer and go to the PowerPoint Web site, click Microsoft PowerPoint.

Conclusion

I've only briefly touched on how to develop smart tag DLLs in Office XP. The Smart Tags SDK provides additional information about:

• Registering additional smart tag types.
• Using an Extensible Markup Language (XML) file to register additional smart tag values and actions, instead of "hard-coding" these values into your smart tag DLLs.
• Troubleshooting smart tag development issues.
• Deploying smart tag solutions in a corporate desktop or Internet scenario.
• Developing smart tag DLLs by using other COM-based languages such as Microsoft® Visual C++®.

If you're interested in extending the code samples discussed in this article, be sure to see the Smart Tags SDK.