Smart Tags Architecture

Article
02/04/2013

The Office development tools in Visual Studio 2010 provide a flexible smart tag object model that enables you to quickly add smart tags to Microsoft Office Word documents and Microsoft Office Excel workbooks. For advanced scenarios, you can also create your own smart tag recognizers and access data that is stored in the smart tag.

For more information about smart tags, see Smart Tags Overview.

Applies to: The information in this topic applies to document-level projects and application-level projects for Excel 2007 and Word 2007. For more information, see Features Available by Office Application and Project Type.

Object Model Overview

The smart tag object model separates smart tags from the actions that smart tags perform. The following sections describe the main objects you use to create smart tags. For code examples that demonstrate how to add smart tags to a document, see How to: Add Smart Tags to Word Documents and How to: Add Smart Tags to Excel Workbooks.

Smart Tags

In your code, a smart tag is a Microsoft.Office.Tools.Word.SmartTag or Microsoft.Office.Tools.Excel.SmartTag object. These objects include the following properties:

Terms and Expressions. These properties contain the recognizable terms for the smart tag. To specify a simple string, add the string to the Terms property. To specify a complex string, add a regular expression that describes the string to the Expressions property.
Actions. This property contains the actions to perform when the user selects the smart tag.
Caption. This property specifies the label of the smart tag.

Actions

When the user selects your smart tag, the user can perform one or more actions that are specific to the smart tag. Each action is represented by a Microsoft.Office.Tools.Word.Action or Microsoft.Office.Tools.Excel.Action object. These objects provide theBeforeCaptionShow and Click events:

The BeforeCaptionShow event is raised just after the user clicks the smart tag icon, but before the smart tag menu is displayed. Handle this event if you want to modify the title of the action in the smart tag menu at run time.
The Click event is raised when the user clicks the title of the action in the smart tag menu. Handle this event to run code when the user clicks the action.

The event handlers for these events receive an Microsoft.Office.Tools.Excel.ActionEventArgs or Microsoft.Office.Tools.Word.ActionEventArgs object that provides access to the recognized text and the location of the text.

Creating Smart Tags

The way that you create a smart tag depends on whether your project targets the .NET Framework 3.5 or the .NET Framework 4.

When you target the .NET Framework 3.5, SmartTag and Action are classes that you can instantiate directly. The following code example demonstrates how to create a simple smart tag in a Word project that targets the .NET Framework 3.5. To use this example, run the code from the ThisDocument class in a document-level project or the ThisAddIn class in an application-level project.

Dim simpleSmartTag As Microsoft.Office.Tools.Word.SmartTag =
        New Microsoft.Office.Tools.Word.SmartTag(
        "www.microsoft.com/Demo#DemoSmartTag",
        "Test Smart Tag")
Dim simpleAction As Microsoft.Office.Tools.Word.Action = 
    New Microsoft.Office.Tools.Word.Action("Test Action")

simpleSmartTag.Terms.Add("blue")
simpleSmartTag.Actions = New Microsoft.Office.Tools.Word.Action() { _
    simpleAction}
Me.VstoSmartTags.Add(simpleSmartTag)

Microsoft.Office.Tools.Word.SmartTag simpleSmartTag =
    new Microsoft.Office.Tools.Word.SmartTag(
    "www.microsoft.com/Demo#DemoSmartTag",
    "Test Smart Tag");
Microsoft.Office.Tools.Word.Action simpleAction = 
    new Microsoft.Office.Tools.Word.Action("Test Action");

simpleSmartTag.Terms.Add("blue");
simpleSmartTag.Actions = new Microsoft.Office.Tools.Word.Action[] { 
    simpleAction };
this.VstoSmartTags.Add(simpleSmartTag);

When you target the .NET Framework 4, SmartTag and Action are interfaces that you cannot instantiate directly. Instead, you must use the CreateSmartTag and CreateAction methods provided by the Globals class in your project to get instances of these objects. For more information about the Globals class, see Global Access to Objects in Office Projects. The following code example demonstrates how to create a simple smart tag in a Word project that targets the .NET Framework 4. To use this example, run the code from the ThisDocument class in a document-level project or the ThisAddIn class in an application-level project.

Dim simpleSmartTag As Microsoft.Office.Tools.Word.SmartTag =
    Globals.Factory.CreateSmartTag(
        "www.microsoft.com/Demo#DemoSmartTag",
        "Test Smart Tag")
Dim simpleAction As Microsoft.Office.Tools.Word.Action =
    Globals.Factory.CreateAction("Test Action")

simpleSmartTag.Terms.Add("blue")
simpleSmartTag.Actions = New Microsoft.Office.Tools.Word.Action() { _
    simpleAction}
Me.VstoSmartTags.Add(simpleSmartTag)

Microsoft.Office.Tools.Word.SmartTag simpleSmartTag =
    Globals.Factory.CreateSmartTag(
    "www.microsoft.com/Demo#DemoSmartTag",
    "Test Smart Tag");
Microsoft.Office.Tools.Word.Action simpleAction =
    Globals.Factory.CreateAction("Test Action");

simpleSmartTag.Terms.Add("blue");
simpleSmartTag.Actions = new Microsoft.Office.Tools.Word.Action[] { 
    simpleAction };
this.VstoSmartTags.Add(simpleSmartTag);

For further instructions and code examples that demonstrate more complex smart tags, see How to: Add Smart Tags to Word Documents and How to: Add Smart Tags to Excel Workbooks.

Creating Smart Tag Recognizers

If you want to customize the default smart tag recognition behavior, you can create your own smart tag recognizer. The way that you do this depends on whether your project targets the .NET Framework 3.5 and the .NET Framework 4.

Default Text Recognition Behavior

When a user types text in a document or workbook, Word and Excel create a list of tokens from the text. The default smart tag recognizer receives this list of tokens and the complete text typed by the user. The default recognizer identifies a smart tag if one of the following conditions is met:

One of the strings in the Terms property exactly matches one of the tokens in the document or workbook.
One of the regular expressions in the Expressions property is matched in the complete text typed by the user.

Word and Excel parse strings that contain embedded spaces, or strings that combine letters, numbers, and symbols, into separate tokens when a user types them. For example, if the user types "sales report", Word and Excel creates the tokens "sales" and "report". Similarly, if the user types "2005sales", Word and Excel create the tokens "2005" and "sales".

If you want to make your smart tag recognize a string that contains embedded spaces or a string that combines letters, numbers, and symbols, do not add the string to the Terms property. Instead, add a regular expression that describes the string to the Expressions property, or create your own recognizer that searches for the string.

Creating Smart Tag Recognizers in Projects that Target the .NET Framework 4

To create your own smart tag recognizer, define a class that implements the Microsoft.Office.Tools.Word.ISmartTagExtension or Microsoft.Office.Tools.Excel.ISmartTagExtension interface. In your implementation of the ISmartTagExtension.Recognize method, search the text for smart tag terms and register the smart tag with Word or Excel if a smart tag term is found. To register a smart tag, call the PersistTag method of the context parameter of the Recognize method.

The following code example demonstrates how to create a simple smart tag class with a custom recognizer in a Word project that targets the .NET Framework 4.

Public Class SmartTagWithCustomRecognizer
    Implements Microsoft.Office.Tools.Word.ISmartTagExtension

    Private theSmartTag As Microsoft.Office.Tools.Word.SmartTag

    Public Sub New()
        theSmartTag = Globals.Factory.CreateSmartTag("www.microsoft.com/Demo#DemoSmartTag",
            "Test Smart Tag", Me)
        Dim simpleAction As Microsoft.Office.Tools.Word.Action = Globals.Factory.CreateAction("Test Action")
        theSmartTag.Actions = New Microsoft.Office.Tools.Word.Action() {simpleAction}
    End Sub

    Private Sub Recognize(ByVal text As String,
        ByVal site As Microsoft.Office.Interop.SmartTag.ISmartTagRecognizerSite,
        ByVal tokenList As Microsoft.Office.Interop.SmartTag.ISmartTagTokenList,
        ByVal context As Microsoft.Office.Tools.Word.SmartTagRecognizeContext) _
        Implements Microsoft.Office.Tools.Word.ISmartTagExtension.Recognize

        Dim index As Integer = text.IndexOf("blue")
        If index >= 0 Then
            context.PersistTag(index, 4, Nothing)
        End If
    End Sub

    Public ReadOnly Property ExtensionBase() As Object _
        Implements Microsoft.Office.Tools.Word.ISmartTagExtension.ExtensionBase
        Get
            Return theSmartTag
        End Get
    End Property
End Class

public class SmartTagWithCustomRecognizer : Microsoft.Office.Tools.Word.ISmartTagExtension
{
    private Microsoft.Office.Tools.Word.SmartTag theSmartTag;

    public SmartTagWithCustomRecognizer()
    {
        theSmartTag = Globals.Factory.CreateSmartTag("www.microsoft.com/Demo#DemoSmartTag", 
            "Test Smart Tag", this);
        Microsoft.Office.Tools.Word.Action simpleAction = Globals.Factory.CreateAction("Test Action");
        theSmartTag.Actions = new Microsoft.Office.Tools.Word.Action[] { simpleAction };
    }

    public void Recognize(string text, Microsoft.Office.Interop.SmartTag.ISmartTagRecognizerSite site, 
        Microsoft.Office.Interop.SmartTag.ISmartTagTokenList tokenList,
        Microsoft.Office.Tools.Word.SmartTagRecognizeContext context)
    {
        int index = text.IndexOf("blue");
        if (index >= 0)
        {
            context.PersistTag(index, 4, null);
        }
    }

    public object ExtensionBase
    {
        get { return theSmartTag; }
    }
}

For further instructions and code examples that demonstrate more complex smart tag classes with custom recognizers, see How to: Create Smart Tags With Custom Recognizers in Word and .NET Framework 4 and How to: Create Smart Tags With Custom Recognizers in Excel and .NET Framework 4.

Creating Smart Tag Recognizers in Projects that Target the .NET Framework 3.5

To create your own smart tag recognizer, derive a class from Microsoft.Office.Tools.Word.SmartTag or Microsoft.Office.Tools.Excel.SmartTag and then override the SmartTag.Recognize method in the class. In your method, search the text for smart tag terms and register the smart tag with Word or Excel if a smart tag term is found. To register a smart tag, call the PersistTag method that your class derives from Microsoft.Office.Tools.Word.SmartTag or Microsoft.Office.Tools.Excel.SmartTag.

The following code example demonstrates how to create a simple smart tag class with a custom recognizer in a Word project that targets the .NET Framework 3.5.

Public Class SmartTagWithCustomRecognizer 
    Inherits Microsoft.Office.Tools.Word.SmartTag

    Public Sub New()
    MyBase.New("https://www.contoso.com/Demo#DemoSmartTag", _
        "Test Smart Tag")
        Dim simpleAction As Microsoft.Office.Tools.Word.Action = _
            New Microsoft.Office.Tools.Word.Action("TestAction")
        Me.Actions = new Microsoft.Office.Tools.Word.Action() { simpleAction }
    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)

        Dim index As Integer = text.IndexOf("blue")
        If index >= 0 Then
            Me.PersistTag(index, 4, Nothing)
        End If
    End Sub
End Class

public class SmartTagWithCustomRecognizer : Microsoft.Office.Tools.Word.SmartTag
{
    public SmartTagWithCustomRecognizer() : base(
        "https://www.contoso.com/Demo#DemoSmartTag", 
        "Test Smart Tag")
    {
        Microsoft.Office.Tools.Word.Action simpleAction = 
            new Microsoft.Office.Tools.Word.Action("TestAction");
        this.Actions = new Microsoft.Office.Tools.Word.Action[] { simpleAction };
    }

    protected override void Recognize(string text, 
        Microsoft.Office.Interop.SmartTag.ISmartTagRecognizerSite site, 
        Microsoft.Office.Interop.SmartTag.ISmartTagTokenList tokenList)
    {
        int index = text.IndexOf("blue");
        if (index >= 0)
        {
            this.PersistTag(index, 4, null);
        }
    }
}

For further instructions and code examples that demonstrate more complex smart tag classes with custom recognizers, see How to: Create Smart Tags With Custom Recognizers in Word and .NET Framework 3.5 and How to: Create Smart Tags With Custom Recognizers in Excel and .NET Framework 3.5.

Storing and Retrieving Data in the Property Bag

Smart tags can store data in a collection of key and value pairs, known as the property bag. Each value and key in the property bag is a string.

There are two ways to access the property bag:

You can handle the Click or BeforeCaptionShow events of a Microsoft.Office.Tools.Word.Action or Microsoft.Office.Tools.Excel.Action object, and use the Properties property of the event argument parameter to write to and read from the smart tag's property bag. The Properties property returns an ISmartTagProperties object. The ISmartTagProperties interface is available when you add a reference to the Microsoft Smart Tags 2.0 Type Library to your project.
You can create a custom smart tag recognizer by following the instructions above. In your implemention or override of the Recognize method, use the GetNewPropertyBag method of the site parameter to get an ISmartTagProperties object that you can use to write to and read from the smart tag's property bag.

For examples of how to write to and read from the property bag, see the following topics:

Regular Expressions and the Property Bag

When you assign a regular expression to a smart tag, the default recognizer adds a key and value pair for each captured group from the regular expression to the smart tag's property bag.

For an example that demonstrates this behavior, see Walkthrough: Creating a Smart Tag by Using a Document-Level Customization. For more information about captured groups in regular expressions, see Grouping Constructs and The Regular Expression Object Model.

Share via