Developing Smart Tag DLLs
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).
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
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.
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
|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
|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.
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
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
- In Visual Basic 6.0, in the New Project dialog box, double-click ActiveX DLL.
- On the Project menu, click Project1 Properties.
- In the Project Name box, type MicrosoftWebSite. Then click OK.
- In the Properties window, in the (Name) box, type over Class1 and change it to SmartTagRecognizer.
- On the Project menu, click References, select Microsoft Smart Tags 1.0 Type Library, and then click OK.
- In the General Declarations section of the SmartTagRecognizer class code, type the following:
menu, clickAdd Class Module
. Then clickOpen
- In the Properties window, in the (Name) box, type over Class1 and change it to SmartTagAction.
- In the General Declarations section of the SmartTagAction class code, type the following:
menu, clickMicrosoftWebSite Properties
. On theComponent
tab, clickProject Compatibility
. Then clickOK
Save your work.
Now that you've set up the DLL project, let's implement the ISmartTagRecognizer interface.
To implement the ISmartTagRecognizer interface, follow these four steps:
- Provide a unique ID, title, and description for the smart tag recognizer by adding code to the ProgId, Name, and Desc properties in your
SmartTagRecognizerclass 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
- 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
SmartTagRecognizerclass 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
- Provide a list of items to recognize by adding code to your
SmartTagRecognizerclass's General Declarations section and
Class_Initializeroutine 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
- 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
SmartTagRecognizerclass 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.
To implement the ISmartTagAction interface, follow these four steps:
- 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
SmartTagActionclass 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
- 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
SmartTagActionclass 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
- 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
SmartTagActionclass 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
- 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
SmartTagActionclass 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.
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:
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.
To test your smart tag DLL:
- Start Word 2002 and type PowerPoint.
- Press the SPACEBAR or ENTER key to activate the smart tag recognizer, which will underline the word "PowerPoint" with purple dots.
- Rest your mouse pointer on these purple dots, and the Smart Tag Actions button will appear.
- Rest your mouse pointer on the Smart Tag Actions button, and then, to activate the actions menu, click the arrow.
- To start Internet Explorer and go to the PowerPoint Web site, click Microsoft PowerPoint.
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.