Export (0) Print
Expand All

Smart Tags Architecture

Note Required applications

The features in this topic are available only if you have the required applications installed.

For more information, see Features Available by Product Combination.

  • One of these development environments:

    VSTO 2005

    -or-

    Visual Studio Team System

  • Microsoft Office 2003

Microsoft Visual Studio 2005 Tools for the Microsoft Office System provides a flexible smart tag object model that enables you to quickly add smart tags to your Visual Studio Tools for Office solutions. For advanced scenarios, you can also create your own smart tag recognizers and access data that is stored in the smart tag.

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 your 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. SmartTagBase 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.

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 your document.

Actions

The Microsoft.Office.Tools.Word.Action and Microsoft.Office.Tools.Excel.Action classes represent the actions that users can perform when they select the smart tag. 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. The Click event is raised when the user selects the title of the action in the smart tag menu.

Default Smart Tag Behavior

When a user types text in a document or workbook, Microsoft Office Word 2003 and Microsoft Office Excel 2003 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 creates 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. For more information, see "Creating Smart Tag Recognizers" in this topic.

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 creating 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 Microsoft.Office.Tools.Word.SmartTag.PersistTag method.

Microsoft.Office.Tools.Excel.SmartTag

Call the Microsoft.Office.Tools.Excel.SmartTag.PersistTag method.

SmartTagBase

Call the CommitSmartTag method of the site parameter of the Recognize method. The site parameter is an ISmartTagRecognizerSite interface, which 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 at: http://msdn.microsoft.com/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 provides 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. The handlers for these events receive an Microsoft.Office.Tools.Word.ActionEventArgs or Microsoft.Office.Tools.Excel.ActionEventArgs. These classes have a Properties property of type ISmartTagProperties, which you can use to write to and read from the smart tag's property bag. The ISmartTagProperties 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 at: http://msdn.microsoft.com/library.

  • 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, which you can use to write to and read from the smart tag's property bag.

For examples of writing to and reading 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 that Converts Temperatures from Fahrenheit to Celsius. For more information on captured groups in regular expressions, see Grouping Constructs and Regular Expression Classes.

See Also

Community Additions

ADD
Show:
© 2014 Microsoft