How to: Add Smart Tags to Word Documents

  • Article

You can add smart tags to Microsoft Office Word documents to recognize text and give the user access to actions that are related to the recognized terms. The code that you write to create and configure a smart tag is the same for document-level and application-level projects, but there are some differences in the way that you associate a smart tag with documents. Smart tags also have different scope in document-level and application-level projects.

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

This topic describes the following tasks:

  • Adding a smart tag by using a document-level customization

  • Adding a smart tag by using an application-level add-in

To run a smart tag, end users must have smart tags enabled in Word or Excel. For more information, see How to: Enable Smart Tags in Word and Excel.

Adding a Smart Tag by Using a Document-Level Customization

Smart tags in document-level customizations are recognized only in the document that is associated with the customization.

To add a smart tag by using a document-level customization

  1. Create a SmartTag object, and configure this object to define the behavior of the smart tag:

    • To specify the text you want to recognize, use the Terms or Expressions properties.

    • To define the actions that users can click on the smart tag, add one or more Action objects to the Actions property.

    For more information, see Smart Tags Architecture.

  2. Add the SmartTag to the VstoSmartTags property of the ThisDocument class.

The following code example creates a smart tag that recognizes the words term and recognize. When the user clicks the smart tag, it displays the positions of the start and end characters of the recognized word. To run this code, add the code to the ThisDocument class, and call the AddSmartTag method from the ThisDocument_Startup event handler.

Note

The following example works in projects that target .NET Framework 4. To use this example in projects that target .NET Framework 3.5, see the comments in the code.

Private WithEvents displayAddress As Microsoft.Office.Tools.Word.Action

Private Sub AddSmartTag()

    ' Create the smart tag for .NET Framework 4 projects.
    Dim smartTagDemo As Microsoft.Office.Tools.Word.SmartTag = Globals.Factory.CreateSmartTag(
        "www.microsoft.com/Demo#DemoSmartTag",
        "Demonstration Smart Tag")

    ' For .NET Framework 3.5 projects, use the following code to create the smart tag.
    ' Dim smartTagDemo As New  _
    '     Microsoft.Office.Tools.Word.SmartTag( _
    '     "www.microsoft.com/Demo#DemoSmartTag", _
    '     "Demonstration Smart Tag")

    ' Specify the terms to recognize.
    smartTagDemo.Terms.Add("term")
    smartTagDemo.Terms.Add("recognize")

    ' Create the action for .NET Framework 4 projects.
    displayAddress = Globals.Factory.CreateAction("To be replaced")

    ' For .NET Framework 3.5 projects, use the following code to create the action.
    ' displayAddress = New Microsoft.Office.Tools.Word.Action("To be replaced")

    ' Add the action to the smart tag.
    smartTagDemo.Actions = New Microsoft.Office.Tools.Word.Action() { _
            displayAddress}

    ' Add the smart tag.
    Me.VstoSmartTags.Add(smartTagDemo)
End Sub

Private Sub DisplayAddress_BeforeCaptionShow(ByVal sender As Object, _
    ByVal e As Microsoft.Office.Tools.Word.ActionEventArgs) _
    Handles displayAddress.BeforeCaptionShow

    Dim clickedAction As Microsoft.Office.Tools.Word.Action = _
        TryCast(sender, Microsoft.Office.Tools.Word.Action)

    If clickedAction IsNot Nothing Then
        clickedAction.Caption = "Display the location of " & e.Text
    End If
End Sub

Private Sub DisplayAddress_Click(ByVal sender As Object, _
    ByVal e As Microsoft.Office.Tools.Word.ActionEventArgs) _
    Handles displayAddress.Click

    Dim termStart As Integer = e.Range.Start
    Dim termEnd As Integer = e.Range.End
    MsgBox("The recognized text '" & e.Text & _
            "' begins at position " & termStart & _
            " and ends at position " & termEnd)
End Sub

private Microsoft.Office.Tools.Word.Action displayAddress;

private void AddSmartTag()
{
    // Create the smart tag for .NET Framework 4 projects.
    Microsoft.Office.Tools.Word.SmartTag smartTagDemo =
        Globals.Factory.CreateSmartTag(
        "www.microsoft.com/Demo#DemoSmartTag",
        "Demonstration Smart Tag");

    // For .NET Framework 3.5 projects, use the following code to create the smart tag.
    // Microsoft.Office.Tools.Word.SmartTag smartTagDemo =
        // new Microsoft.Office.Tools.Word.SmartTag(
        //     "www.microsoft.com/Demo#DemoSmartTag",
        //     "Demonstration Smart Tag");

    // Specify the terms to recognize.
    smartTagDemo.Terms.Add("term");
    smartTagDemo.Terms.Add("recognize");

    // Create the action for .NET Framework 4 projects.
    displayAddress = Globals.Factory.CreateAction("To be replaced"); 

    // For .NET Framework 3.5 projects, use the following code to create the action.
    // displayAddress = new Microsoft.Office.Tools.Word.Action("To be replaced");

    // Add the action to the smart tag.
    smartTagDemo.Actions = new Microsoft.Office.Tools.Word.Action[] { 
        displayAddress };

    // Add the smart tag.
    this.VstoSmartTags.Add(smartTagDemo);

    displayAddress.BeforeCaptionShow += new
        Microsoft.Office.Tools.Word.BeforeCaptionShowEventHandler(
        displayAddress_BeforeCaptionShow);

    displayAddress.Click += new
        Microsoft.Office.Tools.Word.ActionClickEventHandler(
        displayAddress_Click);
}

void displayAddress_BeforeCaptionShow(object sender,
    Microsoft.Office.Tools.Word.ActionEventArgs e)
{
    Microsoft.Office.Tools.Word.Action clickedAction =
        sender as Microsoft.Office.Tools.Word.Action;

    if (clickedAction != null)
    {
        clickedAction.Caption = "Display the location of " +
            e.Text;
    }
}

void displayAddress_Click(object sender,
    Microsoft.Office.Tools.Word.ActionEventArgs e)
{
    int termStart = e.Range.Start;
    int termEnd = e.Range.End;
    System.Windows.Forms.MessageBox.Show("The recognized text '" + e.Text +
        "' begins at position " + termStart.ToString() +
        " and ends at position " + termEnd.ToString());
}

Adding a Smart Tag by Using an Application-Level Add-In

When you add a smart tag by using an application-level add-in, you can specify whether to make the smart tag work only in a specific document, or in all open documents (also called an application-level smart tag).

To add a smart tag to a specific document

  1. Create a SmartTag object, and configure this object to define the behavior of the smart tag:

    • To specify the text you want to recognize, use the Terms or Expressions properties.

    • To define the actions that users can click on the smart tag, add one or more Action objects to the Actions property.

    For more information, see Smart Tags Architecture.

  2. To create a Microsoft.Office.Tools.Word.Document host item for the document that will host the smart tag, use the GetVstoObject method. For more information about creating host items, see Extending Word Documents and Excel Workbooks in Application-Level Add-ins at Run Time.

  3. Add the SmartTag to the VstoSmartTags property of the Microsoft.Office.Tools.Word.Document.

The following code example creates a smart tag in the active document that recognizes the words term and recognize. When the user clicks the smart tag, it displays the positions of the start and end characters of the recognized word. To run this code, add the code to the ThisAddIn class, call the AddSmartTagToDocument method from the ThisAddIn_Startup event handler, and pass a Microsoft.Office.Interop.Word.Document to AddSmartTagToDocument.

Note

The following example works in projects that target .NET Framework 4. To use this example in projects that target .NET Framework 3.5, see the comments in the code.

Private WithEvents displayAddress As Microsoft.Office.Tools.Word.Action

Private Sub AddSmartTagToDocument(ByVal document As Word.Document)
    ' Create a smart tag for .NET Framework 3.5 projects.
    ' Dim smartTagDemo As New  _
    '    Microsoft.Office.Tools.Word.SmartTag( _
    '    "www.microsoft.com/Demo#DemoSmartTag", _
    '    "Demonstration Smart Tag")
    ' Create a smart tag for .NET Framework 4 projects.
    Dim  smartTagDemo As SmartTag = Globals.Factory.CreateSmartTag(
        "www.microsoft.com/Demo#DemoSmartTag",
        "Demonstration Smart Tag")

    ' Specify the terms to recognize.
    smartTagDemo.Terms.Add("term")
    smartTagDemo.Terms.Add("recognize")

    ' Create the action for .NET Framework 3.5 projects.
    ' displayAddress = New Microsoft.Office.Tools.Word.Action("To be replaced")
    ' Create the action for .NET Framework 4 projects.
    displayAddress = Globals.Factory.CreateAction("To be replaced")

    ' Add the action to the smart tag.
    smartTagDemo.Actions = New Microsoft.Office.Tools.Word.Action() { _
            displayAddress}

    ' Get a Document host item for .NET Framework 3.5
    ' Dim vstoDocument As Microsoft.Office.Tools.Word.Document = _
    ' document.GetVstoObject()
    ' Get a Document host item for .NET Framework 4
    Dim vstoDocument As Microsoft.Office.Tools.Word.Document = _
        Globals.Factory.GetVstoObject(document)

    ' Add the smart tag to the document.
    vstoDocument.VstoSmartTags.Add(smartTagDemo)
End Sub

Private Sub DisplayAddress_BeforeCaptionShow(ByVal sender As Object, _
    ByVal e As Microsoft.Office.Tools.Word.ActionEventArgs) _
    Handles displayAddress.BeforeCaptionShow

    Dim clickedAction As Microsoft.Office.Tools.Word.Action = _
        TryCast(sender, Microsoft.Office.Tools.Word.Action)

    If clickedAction IsNot Nothing Then
        clickedAction.Caption = "Display the location of " & e.Text
    End If
End Sub

Private Sub DisplayAddress_Click(ByVal sender As Object, _
    ByVal e As Microsoft.Office.Tools.Word.ActionEventArgs) _
    Handles displayAddress.Click

    Dim termStart As Integer = e.Range.Start
    Dim termEnd As Integer = e.Range.End
    MsgBox("The recognized text '" & e.Text & _
            "' begins at position " & termStart & _
            " and ends at position " & termEnd)
End Sub

private Microsoft.Office.Tools.Word.Action displayAddress;

private void AddSmartTagToDocument(Word.Document document)
{
    Microsoft.Office.Tools.Word.SmartTag smartTagDemo =
        // Create a smart tag for .NET Framework 3.5 projects.
        //    new Microsoft.Office.Tools.Word.SmartTag(
        //    "www.microsoft.com/Demo#DemoSmartTag",
        //    "Demonstration Smart Tag");
        // Create a smart tag for .NET Framework 4 projects.
        Globals.Factory.CreateSmartTag(
            "www.microsoft.com/Demo#DemoSmartTag",
            "Demonstration Smart Tag");

    // Specify the terms to recognize.
    smartTagDemo.Terms.Add("term");
    smartTagDemo.Terms.Add("recognize");

    // Create the action for .NET Framework 3.5 projects.
    // displayAddress = new Microsoft.Office.Tools.Word.Action("To be replaced");
    // Create the action for .NET Framework 4 projects.
    displayAddress = Globals.Factory.CreateAction("To be replaced");

    // Add the action to the smart tag.
    smartTagDemo.Actions = new Microsoft.Office.Tools.Word.Action[] { 
        displayAddress };

    // Get a Document host item for .NET Framework 3.5
    // Microsoft.Office.Tools.Word.Document vstoDocument =
    //    document.GetVstoObject();
    // Get a Document host item for .NET Framework 3.5
    Microsoft.Office.Tools.Word.Document vstoDocument =
        Globals.Factory.GetVstoObject(document);
    // Add the smart tag to the document
    vstoDocument.VstoSmartTags.Add(smartTagDemo);

    displayAddress.BeforeCaptionShow += new
        Microsoft.Office.Tools.Word.BeforeCaptionShowEventHandler(
        displayAddress_BeforeCaptionShow);

    displayAddress.Click += new
        Microsoft.Office.Tools.Word.ActionClickEventHandler(
        displayAddress_Click);
}


void displayAddress_BeforeCaptionShow(object sender,
    Microsoft.Office.Tools.Word.ActionEventArgs e)
{
    Microsoft.Office.Tools.Word.Action clickedAction =
        sender as Microsoft.Office.Tools.Word.Action;

    if (clickedAction != null)
    {
        clickedAction.Caption = "Display the location of " +
            e.Text;
    }
}

void displayAddress_Click(object sender,
    Microsoft.Office.Tools.Word.ActionEventArgs e)
{
    int termStart = e.Range.Start;
    int termEnd = e.Range.End;
    System.Windows.Forms.MessageBox.Show("The recognized text '" + e.Text +
        "' begins at position " + termStart.ToString() +
        " and ends at position " + termEnd.ToString());
}

To add a smart tag that works in all open documents

  1. Create a SmartTag object, and configure this object to define the behavior of the smart tag:

    • To specify the text you want to recognize, use the Terms or Expressions properties.

    • To define the actions that users can click on the smart tag, add one or more Action objects to the Actions property.

    For more information, see Smart Tags Architecture.

  2. Add the SmartTag to the VstoSmartTags property of the ThisAddIn class.

The following code example creates a smart tag that recognizes the words term and recognize. When the user clicks the smart tag, it displays the positions of the start and end characters of the recognized word. To run this code, add the code to the ThisAddIn class, and call the AddSmartTag method from the ThisAddIn_Startup event handler.

Note

The following example works in projects that target .NET Framework 4. To use this example in projects that target .NET Framework 3.5, see the comments in the code.

Private WithEvents displayAddress As Microsoft.Office.Tools.Word.Action

Private Sub AddSmartTag()

    ' Create the smart tag for .NET Framework 4 projects.
    Dim smartTagDemo As Microsoft.Office.Tools.Word.SmartTag = Globals.Factory.CreateSmartTag(
        "www.microsoft.com/Demo#DemoSmartTag",
        "Demonstration Smart Tag")

    ' For .NET Framework 3.5 projects, use the following code to create the smart tag.
    ' Dim smartTagDemo As New  _
    '     Microsoft.Office.Tools.Word.SmartTag( _
    '     "www.microsoft.com/Demo#DemoSmartTag", _
    '     "Demonstration Smart Tag")

    ' Specify the terms to recognize.
    smartTagDemo.Terms.Add("term")
    smartTagDemo.Terms.Add("recognize")

    ' Create the action for .NET Framework 4 projects.
    displayAddress = Globals.Factory.CreateAction("To be replaced")

    ' For .NET Framework 3.5 projects, use the following code to create the action.
    ' displayAddress = New Microsoft.Office.Tools.Word.Action("To be replaced")

    ' Add the action to the smart tag.
    smartTagDemo.Actions = New Microsoft.Office.Tools.Word.Action() { _
            displayAddress}

    ' Add the smart tag.
    Me.VstoSmartTags.Add(smartTagDemo)
End Sub

Private Sub DisplayAddress_BeforeCaptionShow(ByVal sender As Object, _
    ByVal e As Microsoft.Office.Tools.Word.ActionEventArgs) _
    Handles displayAddress.BeforeCaptionShow

    Dim clickedAction As Microsoft.Office.Tools.Word.Action = _
        TryCast(sender, Microsoft.Office.Tools.Word.Action)

    If clickedAction IsNot Nothing Then
        clickedAction.Caption = "Display the location of " & e.Text
    End If
End Sub

Private Sub DisplayAddress_Click(ByVal sender As Object, _
    ByVal e As Microsoft.Office.Tools.Word.ActionEventArgs) _
    Handles displayAddress.Click

    Dim termStart As Integer = e.Range.Start
    Dim termEnd As Integer = e.Range.End
    MsgBox("The recognized text '" & e.Text & _
            "' begins at position " & termStart & _
            " and ends at position " & termEnd)
End Sub

private Microsoft.Office.Tools.Word.Action displayAddress;

private void AddSmartTag()
{
    // Create the smart tag for .NET Framework 4 projects.
    Microsoft.Office.Tools.Word.SmartTag smartTagDemo =
        Globals.Factory.CreateSmartTag(
        "www.microsoft.com/Demo#DemoSmartTag",
        "Demonstration Smart Tag");

    // For .NET Framework 3.5 projects, use the following code to create the smart tag.
    // Microsoft.Office.Tools.Word.SmartTag smartTagDemo =
        // new Microsoft.Office.Tools.Word.SmartTag(
        //     "www.microsoft.com/Demo#DemoSmartTag",
        //     "Demonstration Smart Tag");

    // Specify the terms to recognize.
    smartTagDemo.Terms.Add("term");
    smartTagDemo.Terms.Add("recognize");

    // Create the action for .NET Framework 4 projects.
    displayAddress = Globals.Factory.CreateAction("To be replaced"); 

    // For .NET Framework 3.5 projects, use the following code to create the action.
    // displayAddress = new Microsoft.Office.Tools.Word.Action("To be replaced");

    // Add the action to the smart tag.
    smartTagDemo.Actions = new Microsoft.Office.Tools.Word.Action[] { 
        displayAddress };

    // Add the smart tag.
    this.VstoSmartTags.Add(smartTagDemo);

    displayAddress.BeforeCaptionShow += new
        Microsoft.Office.Tools.Word.BeforeCaptionShowEventHandler(
        displayAddress_BeforeCaptionShow);

    displayAddress.Click += new
        Microsoft.Office.Tools.Word.ActionClickEventHandler(
        displayAddress_Click);
}

void displayAddress_BeforeCaptionShow(object sender,
    Microsoft.Office.Tools.Word.ActionEventArgs e)
{
    Microsoft.Office.Tools.Word.Action clickedAction =
        sender as Microsoft.Office.Tools.Word.Action;

    if (clickedAction != null)
    {
        clickedAction.Caption = "Display the location of " +
            e.Text;
    }
}

void displayAddress_Click(object sender,
    Microsoft.Office.Tools.Word.ActionEventArgs e)
{
    int termStart = e.Range.Start;
    int termEnd = e.Range.End;
    System.Windows.Forms.MessageBox.Show("The recognized text '" + e.Text +
        "' begins at position " + termStart.ToString() +
        " and ends at position " + termEnd.ToString());
}

Security

You must enable smart tags in Word. By default, they are not enabled. For more information, see How to: Enable Smart Tags in Word and Excel.

See Also

Tasks

How to: Enable Smart Tags in Word and Excel

How to: Add Smart Tags to Excel Workbooks

How to: Create Smart Tags With Custom Recognizers in Word and .NET Framework 3.5

How to: Create Smart Tags With Custom Recognizers in Excel and .NET Framework 3.5

Walkthrough: Creating a Smart Tag by Using a Document-Level Customization

Walkthrough: Creating a Smart Tag by Using an Application-Level Add-In

Concepts

Smart Tags Architecture

Other Resources

Smart Tags Overview

Developing Office Solutions