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

Starting in Visual Studio 2008 Service Pack 1 (SP1), you can create an application-level smart tag that you can use in every open document. The smart tag recognizes tablespoon measurements in a Microsoft Office Word 2007 document, and provides an action that converts the amount to ounces. It adds the equivalent ounce amount in parentheses after the tablespoon amount.

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

This walkthrough illustrates the following tasks:

• Creating a smart tag that uses a regular expression to recognize strings.

• Creating an action that retrieves data from the smart tag and modifies the recognized smart tag text.

Prerequisites

You need the following components to complete this walkthrough:

• Visual Studio Tools for Office (an optional component of Visual Studio 2008 Professional and Visual Studio Team System).

• Microsoft Office Word 2007.

Visual Studio Tools for Office is installed by default with the listed versions of Visual Studio. To check whether it is installed, see Installing Visual Studio Tools for Office.

Creating a New Project

The first step is to create a Word add-in project.

To create a new project

• Create a Word add-in project with the name My Recipe Smart Tag, using either Visual Basic or C#.

  For more information, see How to: Create Visual Studio Tools for Office Projects.

Visual Studio adds the My Recipe Smart Tag project to Solution Explorer.

Configuring the Project

The project needs a reference to the smart tag DLL, and also needs to use regular expressions.

To configure your project

1. On the Project menu, click Add Reference.

2. On the COM tab, select Microsoft Smart Tags 2.0 Type Library and click OK.

3. In Solution Explorer, right-click ThisDocument.vb (in Visual Basic) or ThisDocument.cs (in C#), and then click View Code.

4. Add the following line of code to the top of the file.

   Imports System.Text.RegularExpressions
   

   using System.Text.RegularExpressions;
   

Creating the Smart Tag

To enable the smart tag to find and convert tablespoon measurements, add a regular expression to the list of terms that the smart tag recognizes, and create an action that will be available when the user clicks the smart tag.

To create the smart tag

1. Replace the ThisAddIn_Startup event handler in the ThisAddIn class with the following code. This code creates a SmartTag that represents the Visual Studio Tools for Office smart tag, and adds a regular expression to the list of terms that the smart tag recognizes.

   WithEvents RecipeAction As Microsoft.Office.Tools.Word.Action
   
   Private Sub ThisAddIn_Startup(ByVal sender As Object, _
       ByVal e As System.EventArgs) Handles Me.Startup
   
       Dim SmartTagDemo As New Microsoft.Office.Tools.Word.SmartTag( _
           "www.microsoft.com/Demo#DemoSmartTag", "Recipe Smart Tag")
   
       SmartTagDemo.Expressions.Add(New Regex( _
           "(?'tbsNumber'[+-]?\b[0-9])?\s?(tbs|tablespoons|tablespoon)\b"))
   

   private Microsoft.Office.Tools.Word.Action RecipeAction;
   
   private void ThisAddIn_Startup(object sender, System.EventArgs e)
   {
       Microsoft.Office.Tools.Word.SmartTag SmartTagDemo =
           new Microsoft.Office.Tools.Word.SmartTag(
           @"www.microsoft.com/Demo#DemoSmartTag",
           @"Recipe Smart Tag");
   
       // Specify the terms to recognize.
       SmartTagDemo.Expressions.Add(new Regex(
           @"(?'tbsNumber'[+-]?\b[0-9])?\s?(tbs|tablespoons|tablespoon)\b"));
   

2. Create a new Action and add it to the Actions property of the smart tag. The Action represents an item that the user can click in the smart tag menu.

   RecipeAction = New Microsoft.Office.Tools.Word.Action("Convert to ounces")
   
   SmartTagDemo.Actions = _
       New Microsoft.Office.Tools.Word.Action() {RecipeAction}
   

   RecipeAction = new Microsoft.Office.Tools.Word.Action(
       @"Convert to ounces");
   
   // Add the action to the smart tag.
   SmartTagDemo.Actions = new
       Microsoft.Office.Tools.Word.Action[] { RecipeAction };
   

3. Attach the smart tag to the VstoSmartTags property of the ThisAddIn class. In C#, attach an event handler to the Click event of the action.

   Me.VstoSmartTags.Add(SmartTagDemo)
   End Sub
   

   // Add the smart tag to the document. 
       this.VstoSmartTags.Add(SmartTagDemo);
   
       RecipeAction.Click += new
           Microsoft.Office.Tools.Word.ActionClickEventHandler(
           RecipeAction_Click);
   }
   

Creating an Event Handler for the Action

The event handler retrieves the tablespoon value from the key tbsNumber, which is in the property bag of the smart tag. The event handler then converts the tablespoon amount to ounces, and inserts the ounce value in parentheses after the tablespoon value.

In this example, the key tbsNumber identifies a captured group from the regular expression assigned to the smart tag. For more information about property bags and regular expressions in Visual Studio Tools for Office smart tags, see Smart Tags Architecture.

To create the event handler

• Copy the following code to the ThisAddIn class.

  Private Sub RecipeAction_Click(ByVal sender As Object, _
      ByVal e As Microsoft.Office.Tools.Word.ActionEventArgs) _
      Handles RecipeAction.Click
  
      Dim value As String = e.Properties.Read("tbsNumber")
      Dim tbsRecipeAmount As Double = System.Convert.ToDouble(value)
      Dim ozRecipeAmount As Double = tbsRecipeAmount * 0.5
      e.Range.InsertAfter(" (" + ozRecipeAmount.ToString() + " oz)")
  End Sub
  

  private void RecipeAction_Click(object sender,
      Microsoft.Office.Tools.Word.ActionEventArgs e)
  {
      string value = e.Properties.get_Read(@"tbsNumber");
      double tbsRecipeAmount = System.Convert.ToDouble(value);
      double ozRecipeAmount = tbsRecipeAmount * 0.5;
      e.Range.InsertAfter(" (" + ozRecipeAmount.ToString() + " oz)");
  }
  

Testing the Application

Now you can test your document to verify that the smart tag converts tablespoon measurements to ounces.

To test your workbook

1. In Word, enable smart tags.

   For more information, see How to: Enable Smart Tags in Word and Excel.

2. Press F5 to run your project.

3. Type a recipe with ingredient amounts measured in tablespoons.

4. Click the smart tag icon that appears over the recognized string, and then click Convert to ounces.

5. Confirm that the ounce equivalent is inserted after the tablespoon amount.

See Also

Tasks

How to: Enable Smart Tags in Word and Excel

How to: Add Smart Tags to Word Documents

How to: Add Smart Tags to Excel Workbooks

How to: Create Smart Tags With Custom Recognizers in Word

How to: Create Smart Tags With Custom Recognizers in Excel

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

Concepts

Smart Tags Overview

Smart Tags Architecture

Change History