VSTO 2005 makes Smart Tags smarter (and easier)


 Smart Tags are VSTO’s newest feature. They have been added to the product since Beta 1 has shipped. VSTO 2005 does for Smart Tags what it did for Action Pane, makes it easy and understandable for a .net programmer. Smart Tags in Office have been around since Office XP and updated in Office 2003. The concept of the SmartTag is cool; it recognizes some text and allows you to attach actions to the text. For example if you have a stock symbol you can recognize the text and attach an action, like open the stock quote web site for that symbol.  Before VSTO there were two basic ways to create a Smart Tag; using XML or creating a DLL.

Using XML allows you to create a simple XML file that defines the Recognizer and the Action to take. Office XP only allows exact text matches, in Office 2003 support was added for Regular Expressions (RegEx). These XML files are called Microsoft Office Smart Tag Lists (MOSTL). MOSTLs are easy to install, just copy them to C:Program FilesCommon FilesMicrosoft SharedSmart TagLISTS. The down side to MOSTLs are that the actions are limited to Hyperlinks. They are also limited by passing the entire text that is recognized to the Hyperlink as a {Text} parameter. This is a problem if the text that you want to pass is a substring of the text recognized, for example if your RegEx matches “Bug: 12345” but you only want to pass 12345 to the Hyperlink. Another problem with MOSTLs are that they must be installed on all desktops prior to opening the document. MOSTLs are also global to all applications that support SmartTags and all documents. This forces you to be more conservative with your recognizers because you do not want any false hits. A 5 digit number in one type of document may be a policy number and in another may be a claim number.

The second way to create a SmartTag is to create a DLL (Don’t go there if you have a weak stomach). The SmartTag DLL is the most powerful, and complicated, way to create SmartTags. They are more difficult to install and create. They require you to create a separate Recognizer and Action class that Inherits from 2 different interfaces. The interfaces are not very .Net friendly and are difficult to understand. These SmartTags are also global in scope to the machine just like the MOSTLs, although I believe that you can make them scoped to the document as part of a smart doc solution (I haven’t actually been able to figure this out yet, too painful)

VSTO SmartTags are much easier to use and understand. They offer the simplicity of the MOSTL with the power of the SmartTag DLL. They are scoped to the document they are part of which means that you can be very aggressive about the text you recognize. You can also customize the actions more tightly with the recognized text. Another great feature is that you have access to the range object of the recognized text and access every other part of the VSTO solution including action panes.

So let’s take a look at what it takes to create a VSTO Smart Tag.

1.      Create a New VSTO Word or Excel Project

2.      Add a COM Reference to the Microsoft Smart Tags 2.0 Type Library

3.      Create a Class that Inherits from Microsoft.Office.Tools.Word.SmartTags.SmartTag

4.      Add Actions which are the menu items that come up

5.      Add Recognizers, either RegEx or Text

6.      Add the Event Handlers for the click event of the actions

7.      Add the SmartTag Instance to the documents VSTOSmartTags Collection

That’s it we are done. We now have SmartTag support in our VSTO document.

Here is the Entire Code for the SmartTag Class. This sample recognizes the “Bug 12345” or “Hello”

 

Imports System.Text.RegularExpressions

Imports Microsoft.Office.Tools.Word

Imports Microsoft.Office.Interop.SmartTag

 

Public Class MySmartTag

    Inherits SmartTag

 

    ‘Declare Actions for the SmartTag

    WithEvents OpenMessageBox As Action

    WithEvents SayHello As Action

 

    Sub New()

        MyBase.New(“www.microsoft.com/VSTO#MyFirstSmartTag”, “My First VSTO SmartTag”)

 

        ‘Menu Items, Text to display on the SmartTag Menu

        OpenMessageBox = New Action(“Echo Text to a MessageBox”)

        SayHello = New Action(“Say Hello”)

 

        ‘Add the Actions to the SmartTag

        Actions = New Action() {OpenMessageBox, SayHello}

        ‘Create a RegEx recognizer

        Expressions.Add(New Regex(“[B|b]ugsd{5,6}”))

        ‘you can also add exact text matches the same way

        Terms.Add(“Hello”)

    End Sub

 

    Protected Overrides Sub Recognize(ByVal text As String, ByVal site As Microsoft.Office.Interop.SmartTag.ISmartTagRecognizerSite, ByVal tokenList As Microsoft.Office.Interop.SmartTag.ISmartTagTokenList)

        ‘Gives you access to the raw tokens as they are being fired

        ‘Can handle advanced dynamic tag recognizers, like looking

        ‘text up in a database for a match

    End Sub

 

    Private Sub OpenMessageBox_Click(ByVal sender As Object, ByVal e As Microsoft.Office.Tools.Word.ActionEventArgs) Handles OpenMessageBox.Click

        ‘Fire Message Box with the text

        MessageBox.Show(“The SmartTag recognized is : “ & e.Range.Text)

    End Sub

 

    Private Sub SayHello_Click(ByVal sender As Object, ByVal e As Microsoft.Office.Tools.Word.ActionEventArgs) Handles SayHello.Click

        ‘Set the SmarTag Text

        e.Range.Text = “Hello World”

    End Sub

 

End Class

 

 

Public Class ThisDocument

    Private Sub ThisDocument_Startup(ByVal sender As Object, ByVal e As System.EventArgs) Handles Me.Startup

        ‘Add the SmartTag to the collection on startup

        VSTOSmartTags.Add(New MySmartTag())

    End Sub

 

    Private Sub ThisDocument_Shutdown(ByVal sender As Object, ByVal e As System.EventArgs) Handles Me.Shutdown

    End Sub

End Class

 

 

 

Comments (18)

  1. Paul,

    which version of Visual Studio 2005 should I be using if I want to try out the features you are talking about?

    thanks,

    John

  2. Paul Stubbs says:

    VSTO 2005 Smart Tags will be available in Beta 2 of Whidbey.

  3. mark says:

    I’d recently made my first MOSTL for Excel and had the same drawbacks, 1. limited to URLS 2. MOSTL stored externally.

    Therefore smart tag solutions "as is" in Excel aren’t for me, however your VSTO words offered encouragement for what’s to come.

    Will there be a day when I can use VSTO as a stand-alone app or as part of Excel? I currently don’t want to install Visual Studio .net

    Thanks for the Post,

    Mark

  4. Paul Stubbs says:

    In order to create VSTO 2005 solutions you will need Visual Studio 2005 and Office 2003 Professional. Now you can create VSTO solutions and deploy the solution to users with only Office Pro installed.

  5. mark says:

    Awesome, thanks. I was mistakenly under the impression I needed to install Visual Studio .Net also.

  6. mark says:

    Sorry, I misread your answer earlier. I do need to install VS to use VSTO, makes sense.

    Thanks.

  7. Paul Stubbs says:

    I updated the code sample for VSTO 2005 Beta 2.

  8. Pierrot says:

    Just a little comment. I really find the new VSTOSmartTags great. But the Actions still lack a little flexibility. We’re basically talking about a contextual menu, attached to a recognized piece of text. It looks like a menu, it feels like a menu, it behaves like a menu and now we’re even building them (actions)in a way very reminiscent of true menu. How could we use the menu interface to be able to customize the actions completely (icons, submenus, show/don’t show info…).

    An other thought. How could we pass something else to the recognizers instead of the text? since we already can access the type (Cell..), why don’t we pass a generic object instead, giving us ,after type testing, access to its members?

  9. kourosh says:

    Hi,

    Thanks for your article,

    I have just done what you have written in C# but i get following error,

    Partial declarations of ‘WordSmartTag.ThisDocument’ must not specify different base classes

    here is my class

    public partial class ThisDocument : SmartTag

  10. Tunc Samiloglu says:

    Hi,

    Thank you for this article!

    I have completed my smart tag project, and it works fine inside the VS05 tool.  However, how can I now package my smart tag and distribute to other users to use in Word 2003?

    Thank you.

  11. I thought I’d make a little table: VSTO Version Office 2003 Office 2007 Additional Information doc app

  12. theWizard says:

    Hi,

    This article gave me a better view on how smart tags are used, but the problem is that it’s not working for Office 2007 and VSTO 2005 SE.

    In those programs you don’t have "VSTOSmartTags" because it’s all application based and not document based.

    Could you help me to convert your example to Office 2007? Cause their isn’t any documentation  on this issue, not even on the MSDN.

    Thanks in advance

  13. pstubbs says:

    Thanks for your feedback. Currently VSTO 2005 smarttags only work for Office 2003 Pro Word and Excel applications. VSTO 2005 SE added support for Office 2003 and Office 2007 add-ins. VSTO ‘Orcas’ will add support for Office 2007 Word and Excel document projects which include smarttags.  Another option is that your existing VSTO 2005 solutions will continue to work in Office 2007 using the VSTO 2005 SE runtime.

    I know this is a little complicated and confusing because of the intersection of 3 products all on different ship schedules. So let me know if you have any other questions.

  14. theWizard says:

    Well I hope you can help me with this problem. I’m trying to add application based smart tags with VSTO 2005SE in Word 2007. I tried to add 2 different smart tags. One standard and one custom with this code:

    Dim sTag1 As New Microsoft.Office.Tools.Word.SmartTag("www.microsoft.com/Demo#DemoSmartTag", _

           "Demonstration Smart Tag")

           sTag1.Expressions.Add(New Regex("(?’number'[+-]?b[0-9]+)?s?(F|f)b"))

           action1 = New Microsoft.Office.Tools.Word.Action("Convert to Celsius")

           sTag1.Actions = New Microsoft.Office.Tools.Word.Action() {action1}

           Dim sTag2 As New CustomSmartTag()

           Try

               ‘Range.InsertXML(

               For Each doc As Word.Document In Me.Application.Documents

                   doc.SmartTags.Add("www.microsoft.com/Demo#DemoSmartTag")

                   doc.SmartTags.Add("http://www.contoso.com/Demo#DemoSmartTag")

                   Me.Application.SmartTagRecognizers.ReloadRecognizers()

                   ‘Force Word to check for smart tags when the document loads

                   doc.RecheckSmartTags()

               Next

               ‘MessageBox.Show(Me.Application.ActiveDocument.SmartTags.Count.ToString())

           Catch ex As System.Exception

               MessageBox.Show(ex.Message)

           End Try

    When I count the smart tags I see that there are   2 smartags in the document. But when I typ something that matches te tag it wont’ work.

    Thanks in advance

  15. pstubbs says:

    Hi,

    VSTO smart tags are document based. So you can use VSTO 2005 to create SmartTags for Office 2003 Pro or VSTO ‘Orcas’ (when it ships later this year) to create Office 2007 SmartTags. VSTO SE does not have support for SmartTags. You could create a VSTO 2005 Office 2003 project and run it in Office 2007.

    – Paul

  16. Hannibal says:

    Hello,

    First, thank you for this excellent article

    wish you continue writing in such subject !

    I ‘d like to know if VSTO 2005 Smart Tags support both Office XP and office 2003 ?

    Else, How can I write Smart Tags both XP and 2003 Office compatible !

    Thanks.