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
Application-level projects
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.
Object Model 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.
Creating Smart Tag Recognizers
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 |
|---|---|
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. |
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.
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.
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
Walkthrough: Creating a Smart Tag by Using an Application-Level Add-In