Developing Simple Smart Tags

This content is no longer actively maintained. It is provided as is, for anyone who may still be using these technologies, with no warranties or claims of accuracy with regard to the most recent product version or service release.

 

Paul Cornell
Microsoft Corporation

May 2001

Applies to:
   Microsoft® Office XP

Summary: This article describes how to create, deploy, and manage simple smart tags for Microsoft Office XP by using Extensible Markup Language (XML) files. (10 printed pages)

Download ODC_stXML.exe.

Contents

Introduction
Creating Your First Simple Smart Tag
Exploring the Smart Tag XML Syntax
Deploying Simple Smart Tags by Using the Visual Studio Installer
Updating Simple Smart Tags
Conclusion

Introduction

Smart tags are a new feature in Microsoft® Word 2002, Microsoft Excel 2002, Microsoft Outlook® 2002 (when Word is enabled as your e-mail editor), and Microsoft Internet Explorer (when Microsoft Office XP or one of the standalone applications mentioned above is installed on your computer) that allows text to be labeled with contextual information while users type. For example, "Paul Cornell" could be labeled as a person's name, and "MSFT" could be labeled as a stock ticker symbol. Once the text has been labeled, users can choose from a list of available actions that apply to that text. For example, a user might want to create a new contact record in Outlook with "Paul Cornell" already placed into the Full Name field. Similarly, a user might want to get the latest stock price for "MSFT" from the MoneyCentral Web site on the Microsoft Network (MSN®). Smart tags makes such features easy: the user can rest the mouse pointer on "Paul Cornell," click the Smart Tag Actions button, and select Add to Contacts. Likewise, the user can rest the mouse pointer on "MSFT," click the Smart Tag Actions button, and then click Stock quote on MSN Money Central. Smart tags are extensible, so you can create your own recognizable strings, category labels, and customizable actions for those categories as well.

There are several options for creating your own smart tags. For dynamic, highly-interactive smart tags, you can use a Component Object Model (COM)-based application development system such as Microsoft Visual Basic® or Microsoft Visual C++®. For simple smart tags you can use a text editor or HTML editor (such as Notepad or Microsoft FrontPage®). This article focuses on the simple smart tag approach. For information on creating dynamic, highly interactive smart tags by using Visual Basic, you can start with another article I've written titled "Developing Smart Tag DLLs." For more information on smart tag development in general, download the Smart Tag Software Development Kit (SDK).

**Note   **I use the term "simple smart tag" in this article to mean a smart tag that allows a user to only browse to a Web site (and possibly pass the actionable text as a parameter to the Web site).

You can create a simple smart tag by adhering to the smart tag list schema, a syntax that Microsoft has designated so that Microsoft Office XP can recognize certain text strings as actionable, as well as provide the appropriate actions for these text strings. The smart tag list schema is described in Extensible Markup Language (XML) format. Explaining XML is beyond the scope of this article; for more information on XML, see the MSDN Online XML Developer Center.

When you've finished typing your simple smart tag schema, you will need to save the file containing the XML (also known as an XML list description file) to a specific path on the end user's computer. Office XP uses this path to find the functionality for locating and labeling actionable text. A deployment tool such as the Microsoft Visual Studio® Installer can automate the deployment of XML list description files.

If you want to provide updates to the available text and actions for an XML list description file you've already deployed, you can add simple XML files to a Web server (such as the one included with Microsoft Internet Information Services) so that end users can automatically pull updates down to their computers.

I will explain how to create, save, deploy, test, and manage these XML list description files in the sections that follow.

Creating Your First Simple Smart Tag

To create your first XML list description file:

  1. Make sure all of your smart tag-aware applications (Word 2002, Excel 2002, Outlook 2002, and Internet Explorer) are shut down.

  2. Start Notepad and type the following (or view the file msdnodc.xml in the sample download):

    <FL:smarttaglist xmlns:FL="urn:schemas-microsoft-com:smarttags:list">
    <FL:name>MSDN Office Developer Center Related Terms</FL:name> 
    <FL:lcid>1033</FL:lcid>
    <FL:description>A list of MSDN Office Developer Center related terms
        for recognition, as well as a set of actions that work with
        them.</FL:description>
    <FL:moreinfourl>http://msdn.microsoft.com/office</FL:moreinfourl>
    <FL:smarttag type="urn:schemas-microsoft-com:smarttags#msdnterms">
        <FL:caption>MSDN Office Developer Center Related Terms</FL:caption>
        <FL:terms>
            <FL:termlist>access, developer, excel, msdn, office,
                outlook, powerpoint, vba, visual, word, xp</FL:termlist>
        </FL:terms>
        <FL:actions>
            <FL:action id="ODCWebSite"> 
             <FL:caption>&amp;MSDN Office Developer Web site</FL:caption>
          <FL:url>http://msdn.microsoft.com/office</FL:url>
            </FL:action>
                <FL:action id="MSDNWebSite">
                <FL:caption>MSDN Main &amp;Web site</FL:caption>
                <FL:url>http://msdn.microsoft.com</FL:url>
            </FL:action>
                <FL:action id="OfficeWebSite">
                <FL:caption>Microsoft &amp;Office Web site</FL:caption>
                <FL:url>http://www.microsoft.com/office</FL:url>
            </FL:action>
        </FL:actions>
    </FL:smarttag>
    </FL:smarttaglist>
    

3. Save the file as msdnodc.xml in the following directory: C:\Program Files\Common Files\Microsoft Shared\Smart Tag\Lists.

4. Start Word 2002 and type one or more of the following words, separated by spaces or carriage returns: access, developer, excel, msdn, office, outlook, powerpoint, vba, visual, word, or xp.

5. Underneath any of the words you typed in step four you will notice a dotted purple underline. Rest the mouse pointer on one of these words, click the Smart Tag Actions button, and click one of the choices on the context menu, such as MSDN Office Developer Web site, MSDN Main Web site, or Microsoft Office Web site.

Exploring the Smart Tag XML Syntax

The XML in the previous exercise conforms to a specific syntax that Microsoft has defined for simple smart tags. To enable you to customize the XML to meet your own needs, I will explain the syntax.

The first line of text, <FL:smarttaglist xmlns:FL="urn:schemas-microsoft-com:smarttags:list">, defines the root element and the namespace for the smart tag. If you're familiar with XML namespaces, you know that the arbitrary string "FL" is an alias for writing the longer "urn:schemas-microosft-com:smarttags:list" at the beginning of every XML opening and closing tag.

Each XML list description file can have a list containing multiple smart tag terms. Table 1 below describes the various XML elements and examples of their use in a simple smart tag XML list description file. Note that if an XML element listed below is not implemented in the exercise above, it is because that smart tag was not designed to be updateable. I will show you an example later in this article of how to create an updateable simple smart tag.

Table 1. Smart tag XML list description elements (in order of appearance)

Element name Description Example
smarttaglist The root element for a smart tag list definition. <FL:smarttaglist xmlns:FL="urn:schemas-microsoft-com:smarttags:list">

{numerous elements...}

<FL:smarttag>...</FL:smarttag>

<FL:/smarttaglist>

name A friendly name for the smart tag recognizer. This element is required. <FL:name>MSDN Office Developer Center Terms</FL:name>
lcid A comma-separated list of "LocaleIDs" or language identifiers for which the smart tag list items will be recognized. If the value of this tag is *, 0, or is not specified, it is assumed that the list works in all locales. Sometimes the host application (for example, Excel) does not specify lcid; in that case, the value is ignored. In Word, language auto-detection determines what the language is. <FL:lcid>1033</FL:lcid>
description A longer string that describes the smart tag. <FL:description>A list of MSDN Office Developer Center

related terms for recognition, as well as a

set of actions that work with them.</FL:description>

moreinfourl A Uniform Resource Locater (URL) where the user can go for more information, supplied by the smart tag developer, on the smart tag recognizer. <FL:moreinfourl>http://msdn.microsoft.com/office</FL:moreinfourl>
updateable A Boolean value; True if the list of terms is updateable. The default value is False. <FL:updateable>true</FL:updateable>
autoupdate A Boolean value; True if the recognizer should automatically update. The default value is False. <FL:autoupdate>true</FL:autoupdate>
lastcheckpoint An ID specifying the last smart tag list update. It is an Integer value that serves as the version number for the last update. If the server has a higher version number than the lastcheckpoint ID when an automatic update is performed, an update occurs. If the operation is successful, the lastcheckpoint ID is updated. <FL:lastcheckpoint>1</FL:lastcheckpoint>
lastupdate An Integer value that specifies when the last update occurred. It represents the number of minutes since 1970. Other than that, it serves no functional role in the update process. Normally, this value is initially set to zero. This element and value must be present for the update process to function correctly. <FL:lastupdate>0</FL:lastupdate>
updateurl A URL to check for updates to this smart tag list. If this element is not specified, the list is not designed to be updateable. <FL:updateurl>http://localhost/smarttags/update.xml</FL:updateurl>
updatefrequency An Integer value that specifies in minutes how often a list should be updated. If this element is not specified, the default value is set to 10,080 (7 days). <FL:updatefrequency>1440</FL:updatefrequency>
smarttag The definition of a smart tag type. A smart tag type is defined by a unique namespace, specified as namespaceURI#tagname. This element is required. <FL:smarttag type="urn:schemas-ms-com:msdn#terms">

{numerous elements...}

</FL:smarttag>

caption The title caption for the smart tag. It replaces any existing caption. <FL:caption>MSDN Office Developer Center related terms</FL:caption>
terms A collection of smart tag terms. <terms>

<termfile>...</termfile>

<termlist>...</termlist>

</terms>

termfile (Reserved for future use) A link to the binary file that contains terms. You can only have one termfile or termlist element per XML file. If both termfile and termlist are present, termlist is used.
Note The tools needed to build a smart tag terms file were not available at the time this article was written, but may be provided in the future.
<FL:filename>terms.dat</FL:filename>
termlist The contents of this element should be a comma-separated list of terms to be recognized. This element is required. <FL:termlist>access, developer, excel,

msdn, office, outlook, powerpoint, vba,

visual, word, xp</FL:termlist>

actions A collection of action elements representing new or revised action identifiers. <FL:actions>

<FL:action>...</FL:action>

</FL:actions>

action An individual action. This element has one attribute called id. id is a required alphanumeric string that uniquely identifies the action that applies to a particular smart tag type. <FL:action id="...">

<FL:caption>...</FL:caption>

<FL:url>...</FL:url>

</FL:action>

url Specifies the URL to activate for an action. <FL:url>http://msdn.microsoft.com/office</FL:url>
caption The action's caption. It replaces any existing caption. <FL:caption>MSDN Main &amp;Web site</FL:caption>

One special case for the url element above is that you can pass in the actionable text as a parameter to the URL by using the syntax {TEXT}. For example, for a stock quote on Money Central, the contents of the url element would be http://moneycentral.msn.com/redir/moneycentralredirect.asp?pageid=SmartTag_1&amp;Target=/scripts/webquote.dll?ipage=qd%26Symbol={TEXT}, where {TEXT} is a stock ticker symbol currently displaying the Smart Tag Actions button (such as "MSFT").

Deploying Simple Smart Tags by Using the Visual Studio Installer

To deploy your simple smart tag, you could simply have end users copy the XML list description file to their C:\Program Files\Common Files\Microsoft Shared\Smart Tag\Lists folders, but this approach can be time-consuming for end users. An easier solution is to use a deployment tool such as the Microsoft Visual Studio Installer. The Visual Studio Installer is available for download at the Visual Studio Web site for licensed users of any Visual Studio 6.0 Professional or Enterprise edition tool; see the Visual Studio Web site for more information on how to download and install the Visual Studio Installer.

To deploy a simple smart tag by using the Visual Studio Installer:

  1. On the Start menu, point to Programs, point to Microsoft Visual Studio 6.0, point to Microsoft Visual Studio 6.0 Enterprise Tools, and then click Visual Studio Installer.

  2. In the New Project dialog box, on the New tab, expand the Visual Studio folder, and then select the Visual Studio Installer Projects folder.

  3. Select the Empty Installer icon, type a name for your new project in the Name box, type a path to your new project in the Location box, and then click Open.

  4. In the Project Explorer window, double-click File System. Right-click File System on Target Machine, point to Add Special Folder, and then click Program Files Folder.

  5. Right-click Program Files Folder, and then click Add Folder. Rename the new folder Common Files.

  6. Right-click Common Files, and then click Add Folder. Rename the new folder Microsoft Shared.

  7. Right-click Microsoft Shared, and then click Add Folder. Rename the new folder Smart Tag.

  8. Right-click Smart Tag, and then click Add Folder. Rename the new folder Lists.

  9. Right-click Lists, and then click Add File(s). Browse to the smart tag XML list description file you want to install on the end user's computer, and then click Open.

  10. In the Project Explorer window, double-click User Interface. Right-click Select Installation Folder, and then click Delete.

    **Note   **If you do not delete the Select Installation Folder dialog box, the Setup Wizard suggests the default folder C:\Program Files\Your-Project-Name to place the XML file. Because you want to put the file into a different location, by deleting this dialog box, you ensure that the file will be placed into the end user's C:\ :\Program Files\Common Files\Microsoft Shared\Smart Tag\Lists folder.

  11. On the Build menu, click Build.

  12. Using Windows Explorer, browse to the path you created in step 3 above. In that path you will find a subfolder named Output. Open the Output folder, and then open the subfolder named DISK_1. In this folder you will find a file with the extension .msi. This is the Visual Studio Installer file you will distribute to end users. To deploy your XML file, end users must simply double-click the .msi file and accept the defaults that the Setup Wizard suggests.

I used Visual Studio Installer to create a .msi file named MSDNODCST.msi (included in the sample download) that downloads the msdnodc.xml file. I have also included the project files that you can use as a start to your own Visual Studio Installer project.

Updating Simple Smart Tags

To allow your XML list description files to be dynamically updateable over the Internet or an intranet, you must provide five additional elements in your XML list definition file: updateable, autoupdate, lastcheckpoint, lastupdate, and updateurl. You should also include the optional updatefrequency element. More information about these elements is included in Table 1 above.

To provide updates to your XML list description files, you must include a helper XML file on your Web server using the following syntax:

<FLUP:smarttaglistupdate xmlns:FLUP="urn:schemas-microsoft-com:smarttags:listupdate">
    <FLUP:checkpoint>400</FLUP:checkpoint>
    <FLUP:smarttaglistdefinition>msdnodc.xml</FLUP:smarttaglistdefinition>
</FLUP:smarttaglistupdate>

The value of the checkpoint element must be greater than the value of the lastcheckpoint element in the XML list description file in order for updates to be pulled down to the end user's computer. The contents of the XML list description file indicated in the smattaglistdefinition element will be pulled down to the end user's computer and will overwrite their existing file.

To test this behavior on your own computer (assuming you have a local Web server), do the following:

  1. Using the sample XML list description file msdnodc.xml discussed earlier in this article, add the following XML between the moreinfourl and smarttag elements (or view the file msdnodcupdate.xml in the sample download):

    <FL:updateable>true</FL:updateable> 
    <FL:autoupdate>true</FL:autoupdate> 
    <FL:lastcheckpoint>1</FL:lastcheckpoint> 
    <FL:lastupdate>0</FL:lastupdate> 
    <FL:updateurl>http://localhost/smarttags/msdnupdate.xml</FL:updateurl> 
    <FL:updatefrequency>5</FL:updatefrequency>
    

    In this example, localhost is the name of your Web server. Place your newly-modified XML list description file in the C:\Program Files\Common Files\Microsoft Shared\Smart Tag\Lists folder on your computer.

  2. On your local Web server, create a virtual directory called smarttags. In the smarttags virtual directory, create a file named msdnupdate.xml with the XML in the "FLUP" namespace above.

    **Note   **The smarttags virtual directory must have full read permissions and allow for anonymous access.

  3. In that same smarttags directory, place a copy of the newly-modified msdnodc.xml file (or the msdnodcupdate.xml file) from step 1 above, with the following change: the termlist element should have some additional terms, such as basic and 2002.

  4. Assuming your have connectivity to your Web server, after five minutes have passed, you can have your computer recognize the new basic and 2002 terms by performing two tasks: first, you must execute at least one of the actions on the smart tag action lists that appear when you type terms such as access, developer, or excel and then click the Smart Tag Actions button (this forces your computer to check for updates to all locally registered smart tags); second, you must restart your smart-tag aware application (this reinitializes all locally-registered smart tags with the new smart tag values and actions). Then you should be able to type basic or 2002 and have the same Smart Tag Options button appear as for the other terms in the list such as access, developer, and excel.

Conclusion

With only a text editor such as Notepad, you can create simple smart tag XML list description files. These simple smart tags can be deployed to an unlimited number of Office XP users by using a deployment tool such as the Visual Studio Installer. In this article, you learned how to create XML list description files that conform to the Microsoft smart tag XML list description schema. You also learned how to deploy your XML list description files by using the Visual Studio Installer. Finally, you learned how to provide updates to users of your XML list description files over the Internet or an intranet.