Using Smart Tags with Research Services for the Microsoft Office System
Microsoft® Office System
Summary: Create a smart tag for use with a research service and discover how to include a smart tag in the research service response. Learn some tricks to enable communication between the smart tag and the research service and explore code examples of both. (11 printed pages)
Smart Tags in the User Interface
Smart Tag Development
Creating a Research Service Smart Tag
Adding a Smart Tag to the Research Service Response
Looking for New Actions
Using the Research Service to Determine the Host Application
Sending Additional Information
What Isn't Supported
The Research feature available in Microsoft® Office 2003 applications allows the user to easily search a number of built-in and online resources, such as a dictionary or news articles. The Research feature is also extensible; a developer can create a Web service, or research service, designed specifically to interact with the Research task pane.
In most research services, the bulk of the work is done on the server; the client-side work is limited to sending a query and then receiving and rendering a response for display in the Research task pane. If you are creating your own research service, there may be situations where you want to provide added functionality at the client level. You can do this by creating a smart tag to run on the client side, and then adding a bit of XML referring the smart tag to the response packet sent by your research service.
In this article, you'll learn about creating a smart tag for use with a research service, you'll find out how to include a smart tag in the research service response, and you'll learn some tricks you can use to communicate between the research service and the smart tag.
This article provides a few examples of Microsoft Visual Basic® .NET code taken from a smart tag DLL and a research service, but does not outline all of the steps to create either the smart tag or the research service on your own. If you would like a detailed walkthrough of creating a smart tag, see Developing Smart Tag DLLs and Building Smart Tags in Microsoft Visual Basic .NET.
For more information on creating a research service, see Customizing the Microsoft Office 2003 Research Task Pane and the Microsoft Office 2003 Research Service Software Development Kit.
Smart tags were introduced in Microsoft Office XP as a tool to provide instant, context-sensitive access to common activities for a string of text matching words of a certain type, (such as person names or dates), or common patterns such as credit card numbers or zip codes. For example, if you type a date in a Word article and then hover your mouse cursor over the date, you see a smart tag action button like the one shown in Figure 1.
Figure 1. The purple dotted underline indicates that a smart tag recognized the date.
If you click the smart tag action button, you see a list of actions appropriate for the recognized text, like the list shown in Figure 2.
Figure 2. Smart tag actions provide quick access to common tasks.
In this general example of a smart tag, the smart tag indicator appears because the text you typed is recognized by the Recognizer class of a smart tag installed on your computer. In the Microsoft Office System, the Research feature does not use a smart tag recognition process to find text to be tagged. Rather, the developer of the research service specifies when and where the smart tag action button should appear. Figure 3 shows the Research task pane with a result that contains a smart tag action button.
Figure 3. You determine the location of the Actions button.
The Microsoft Office System includes several prefabricated smart tags, and the smart tag model provide the infrastructure for a developer to create and distribute customized smart tags. You can create simple smart tags using XML, but most smart tags are dynamic link libraries (DLLs) developed using Microsoft Visual Basic®, Microsoft Visual C++®, Microsoft Visual Basic .NET, or another COM development system.
A smart tag DLL can have two parts:
- A Recognizer class scans the article as you type and flags recognized terms with a purple dotted underline. When the mouse cursor rests on a recognized term, a smart tag action button is displayed.
- An Action class is called when the user clicks the smart tag action button. It provides the list of menu items to display and defines the code that runs when a menu item is selected.
You do not have to provide both a Recognizer and an Action class in the same DLL, as the architecture is loosely coupled; the two are linked together by a namespace defined in the SmartTagName property of each class.
If you are developing a smart tag to be used strictly by a research service, you do not need to create a Recognizer class at all: the research service sends the smart tag action class all the information needed to create an appropriate action list.
You create a smart tag Action class by implementing the ISmartTagAction and ISmartTagAction2 interfaces, and adding code for all of the members of the interfaces. There are three members that are of particular interest when creating smart tags for the Research task pane: SmartTagName, VerbCaptionFromID2, and InvokeVerb2.
The SmartTagName property defines the unique name for the smart tag. The SmartTagName consists of two parts: the namespace URI and a tag name for the smart tag. The two parts are separated by a pound (#) character.
Your research service needs to include the name defined in SmartTagName in the XML response it sends to the Research pane. The SmartTagName property used for the examples included in this article is shown here:
Public ReadOnly Property SmartTagName( _ ByVal SmartTagID As Integer) As String _ Implements SmartTagLib.ISmartTagAction.SmartTagName Get Return "urn:samples-microsoft-com#HelloWorldSmartTag" End Get End Property
When the Research task pane shows an Actions button and the user clicks on it, the user sees a list of possible actions. The text for those actions is determined by the VerbCaptionFromID property. The code for a single action smart tag looks like this:
Public ReadOnly Property VerbCaptionFromID2( _ ByVal VerbID As Integer, _ ByVal ApplicationName As String, _ ByVal LocaleID As Integer, _ ByVal Properties As SmartTagLib.ISmartTagProperties, _ ByVal [Text] As String, _ ByVal Xml As String, _ ByVal Target As Object) As String _ Implements SmartTagLib.ISmartTagAction2.VerbCaptionFromID2 Get Return "Show Hello World" End Get End Property
The code for the action or actions themselves is found in the InvokeVerb2 procedure. The simple example shown here displays a "Hello, World" message box when the action is selected:
Public Sub InvokeVerb2( _ ByVal VerbID As Integer, _ ByVal ApplicationName As String, _ ByVal Target As Object, _ ByVal Properties As SmartTagLib.ISmartTagProperties, _ ByVal [Text] As String, _ ByVal Xml As String, _ ByVal LocaleID As Integer) _ Implements SmartTagLib.ISmartTagAction2.InvokeVerb2 MsgBox("Hello, World!") End Sub
Note You can still use a smart tag created for Office XP with the Smart Tag 1.1 interface in a research service. If you do, the code that runs when an action is selected is in the InvokeVerb method rather than InvokeVerb2, and the text for the action menu is in VerbCaptionFromID.
Once you created and registered the smart tag, you're ready to add it to your research service. The Research Response Content schema provides an Actions node that supports the following children:
- The Insert element inserts text to the current article at the selection point.
- The Copy element copies text to the clipboard.
- The Custom element calls the Action class of a smart tag DLL if it is installed on the client computer.
- The Hyperlink element allows for an action to launch a hyperlink.
- The NewQuery element allows for an action to launch a new query.
For more information about the Research Response Content schema, see the Microsoft Office 2003 Research Service Software Development Kit.
The XML generated by the Response code looks like this:
<Actions> <Custom xmlns:hw="urn:samples-microsoft-com"> <hw:HelloWorldSmartTag>Hello</hw:HelloWorldSmartTag> </Custom> </Actions>
The namespace specified in the Custom element is the namespace of the smart tag. This portion must match the namespace defined in the SmartTagName property of the smart tag's Action class.
The child of the Custom element smart tag is the tag portion of the name defined in the SmartTagName property. Its content substitutes for the recognition process in a non-research service smart tag. Normally, when a smart tag operating in an Office 2003 application recognizes a term, the recognized term is sent to the action's InvokeVerb2 method as part of the recognition process. With a research service smart tag, the research service sends the recognized term to the InvokeVerb2 method as the Text argument and as part of the Xml argument. Given the example above, the InvokeVerb2 method receives a Text argument with this value:
And an XML argument with this value:
'<xml xmlns='urn:samples-microsoft-com'> <HelloWorldSmartTag>Hello</HelloWorldSmartTag></xml>'
You can write the code in InvokeVerb2 to parse either of these values, and take appropriate action according to the value found.
In Visual Basic .NET, you can write the code to create the smart tag portion of the XML response as follows:
Dim myXMLwriter As New XmlTextWriter(ioMemStream, Nothing) With myXMLwriter ... .WriteStartElement("Actions") .WriteStartElement("Custom") .WriteAttributeString("xmlns:hw", "urn:samples-microsoft-com") .WriteElementString("hw:HelloWorldSmartTag", "Hello") .WriteEndElement() ' Custom .WriteEndElement() ' Actions ... End With
Of course, because the work of the smart tag is done on the client computer, you must install that smart tag and register it on the client computer. If it isn't, the research service still works but, by default, the user does not see a menu after clicking the actions button. You can allow the user to install the smart tag as needed by creating an installation package and posting it to a Web page hosted on the Internet or your corporate intranet. You can reference the URL as an attribute of the Custom element:
<Actions> <Custom xmlns:hw="urn:samples-microsoft-com" url="http://www.example.com"> <hw:HelloWorldSmartTag>Hello</hw:HelloWorldSmartTag> </Custom> </Actions>
When a user without the smart tag installed clicks the Actions button, a Check for New Actions menu item is displayed, as shown in Figure 4.
Figure 4. You can provide a URL for new smart tag downloads or updates.
The Check for New Actions menu item is still displayed when the smart tag is installed. Users can check periodically for updates as well as new smart tags.
When a smart tag action is called, the InvokeVerb2 method receives an ApplicationName argument so you can provide different functionality depending on the host application. For example, a single smart tag might provide the ability to insert a table of information in Microsoft Office Excel 2003, insert an image and some text in Microsoft Office Word 2003, and take no action at all in Microsoft Office PowerPoint® 2003 and Microsoft Internet Explorer. When you create a research service smart tag, you can continue to use the smart tag's DLL to determine the application; the smart tag receives the name of the application hosting the Research task pane.
There may be times when you would prefer that the research service determine which, if any, smart tags should be displayed. The name of the application is included in the XML string sent to the Query service; it is the name element of the Query Office Context namespace (urn:Microsoft.Search.Query.Office.Context). You can determine the application name by parsing out the value of the name element, as shown in the following code example:
<WebMethod()> Public Function Query(ByVal queryXml As String) _ As String ... Dim requestXml As New XmlArticle() Dim applicationName As String requestXml.LoadXml(queryXML) Dim nsmRequest As New XmlNamespaceManager(requestXml.NameTable) With nsmRequest .AddNamespace("ns", "urn:Microsoft.Search.Query") .AddNamespace("sp", _ "urn:Microsoft.Search.Office.ServiceParameters") .AddNamespace("oc", _ "urn:Microsoft.Search.Query.Office.Context") End With applicationName = _ requestXml.SelectSingleNode("//oc:Name", nsmRequest).InnerText
Once the application name is known, you can choose which smart tag to display, or whether to display any action at all. The following code adds a smart tag action button to the response only if the application is Microsoft Office Word 2003:
If applicationName = "Microsoft Word" Then .WriteStartElement("Actions") .WriteStartElement("Custom") .WriteAttributeString("xmlns:hw", "urn:samples-microsoft-com") .WriteElementString("hw:HelloWorldSmartTag", "Hello") .WriteEndElement() ' Custom .WriteEndElement() ' Actions End If
Because you, as the research service developer, are crafting the XML that is sent to the smart tag, you are not limited to sending only a single term to the smart tag. You can extend the smart tag's functionality by sending attributes from the research service with more information about the paragraph, heading, host application, or research service from which the smart tag is being called.
For example, suppose you've created a smart tag that takes the user to a page on your Web site with details about the product shown in the Research task pane. You can extend the smart tag to provide another action that takes the user to a Web page listing all products in the same category as the product shown in the Research task pane.
The following XML example shows a research service and a smart tag designed to work with a database of garden flowers:
<xml xmlns='urn:samples-microsoft-com'><FlowerDatabase BloomTime='Spring' Zone='3'>Bleeding Heart </FlowerDatabase></xml>
The XML example is sent to a smart tag named
urn:samples-microsoft-com#FlowerDatabase. In addition to the name of a flower, the smart tag can also use the BloomTime and Zone categories.
The smart tag's InvokeVerb2 method can then parse the XML to determine the BloomTime and Zone categories:Dim requestXml As New XmlArticle() requestXml.LoadXml(Xml) Dim nsmRequest As New XmlNamespaceManager(requestXml.NameTable) nsmRequest.AddNamespace("ns", "urn:samples-microsoft-com") strBloomTime = _ requestXml.SelectSingleNode("//@BloomTime", nsmRequest).Value strZone = _ requestXml.SelectSingleNode("//@Zone", nsmRequest).Value
The Research feature supports nearly all features that are supported by general purpose smart tags. There is one exception: Microsoft Smart Tags 2.0 (the smart tag version written for use with the Microsoft Office System) added support for cascading menus. A cascading menu in a recognized smart tag action in Word 2003 looks like Figure 5.
Figure 5. Action menus can now cascade in general purpose smart tags.
If this smart tag is used in a Research task pane, the same menu items are available, but the look is quite different. Rather than cascading, the menu choices appear with three slashes (///) between each level, as shown in Figure 6.
Figure 6. Cascading menus aren't supported within the Research task pane.
You can easily integrate a general purpose smart tag into a research service. However, if you are developing a smart tag specifically for use in the Research taskpane, you do not need to create a Recognizer class because the research service calls the smart tag's Action class directly. Also, you can enhance your smart tag action by including additional attributes in the XML fragment that references the smart tag.
About the Author
Jan Fransen works with Microsoft Office, Microsoft SQL Server, and Microsoft Visual Studio® .NET to create really useful desktop applications. She enjoys using her skills as a trainer and writer to help other developers do the same. When she's not spending time with her husband and two kids in Minneapolis, Jan works with the talented people at OfficeZealot.com, A23 Consulting, and AppDev Training. You can contact her at Jan@OfficeZealot.com.