Smart Tags Architecture
Important This document may not represent best practices for current development, links to downloads and other resources may no longer be valid. Current recommended version can be found here. ArchiveDisclaimer

Smart Tags Architecture

Applies to

The information in this topic applies only to the specified Visual Studio Tools for Office projects and versions of Microsoft Office.

Document-level projects

  • Excel 2003

  • Excel 2007

  • Word 2003

  • Word 2007

Application-level projects

  • Excel 2007

  • Word 2007

For more information, see Features Available by Application and Project Type.

Visual Studio Tools for Office provides 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 Visual Studio Tools for Office smart tags, see Smart Tags Overview.

The object model for Visual Studio Tools for Office smart tags provides separate classes for smart tags and the actions that smart tags perform. For code examples that demonstrate how to add Visual Studio Tools for Office 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

A Visual Studio Tools for Office smart tag is an instance of any class that derives from the abstract SmartTagBase class. Visual Studio Tools for Office includes two classes that implement the abstract SmartTagBase class: Microsoft.Office.Tools.Word.SmartTag and Microsoft.Office.Tools.Excel.SmartTag. Unless you need to create your own smart tag recognizer, you can use instances of these classes when you add smart tags to a document.

The SmartTagBase class provides the following features:

  • The Terms and Expressions properties, which 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.

  • The Actions property, which contains the actions to perform when the user selects the smart tag.

  • A default smart tag recognizer that compares user input with the contents of the Terms and Expressions properties.

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 an instance of the Microsoft.Office.Tools.Word.Action or Microsoft.Office.Tools.Excel.Action class. These classes provide the BeforeCaptionShow 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 (for Excel) or Microsoft.Office.Tools.Word.ActionEventArgs (for Word) that provides access to the recognized text and the location of the text.

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 in the SmartTagBase class 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.

To create your own smart tag recognizer, derive a new class from SmartTagBase, Microsoft.Office.Tools.Word.SmartTag, or Microsoft.Office.Tools.Excel.SmartTag, and override the Recognize method.

In your implementation of Recognize, you must search the text for smart tag terms and manually register the smart tag with Word or Excel if a smart tag term is found. For examples of how to create recognizers for Visual Studio Tools for Office smart tags, see How to: Create Smart Tags With Custom Recognizers in Word and How to: Create Smart Tags With Custom Recognizers in Excel.

The process for manually registering a smart tag depends on the smart tag class that you are deriving from. The following table lists the different options for registering a smart tag.

Class you are deriving from

How to register the smart tag

Microsoft.Office.Tools.Word.SmartTag

Call the SmartTag.PersistTag method.

Microsoft.Office.Tools.Excel.SmartTag

Call the SmartTag.PersistTag method.

SmartTagBase

Call the CommitSmartTag method of the site parameter of the Recognize method.

The site parameter is an object that implements the ISmartTagRecognizerSite interface. This interface is available when you add a reference to the Microsoft Smart Tags 2.0 Type Library to your project. For more information, see the Smart Tag SDK documentation in the MSDN Library.

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.

Visual Studio Tools for Office smart tags provide two ways of accessing the property bag:

For examples of how to write to and read from the property bag, see How to: Create Smart Tags With Custom Recognizers in Word and How to: Create Smart Tags With Custom Recognizers in Excel.

Regular Expressions and the Property Bag

When you assign a regular expression to a Visual Studio Tools for Office 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.

Show:
© 2016 Microsoft