|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
The information in this topic applies only to the specified Visual Studio Tools for Office projects and versions of Microsoft Office.
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.
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.
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.
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
Call the SmartTag.PersistTag method.
Call the SmartTag.PersistTag method.
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:
You can handle the Click or BeforeCaptionShow events of the Microsoft.Office.Tools.Word.Action or Microsoft.Office.Tools.Excel.Action classes, 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 object that implements the ISmartTagProperties interface. The ISmartTagProperties interface is available when you add a reference to the Microsoft Smart Tags 2.0 Type Library to your project.
You can implement the Recognize method in a class that derives from SmartTagBase, Microsoft.Office.Tools.Word.SmartTag, or Microsoft.Office.Tools.Excel.SmartTag. The site parameter of this method provides a GetNewPropertyBag method that returns an ISmartTagProperties object, which 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 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.