Export (0) Print
Expand All
2 out of 4 rated this helpful - Rate this topic

XML Schema for Smart Tag Lists

 

Tristan Davis
Microsoft Corporation

January 2003

Applies to:
     Microsoft® Office XP

Summary: Learn about the Microsoft Office Smart Tag Lists (MOSTL) schema. This schema can be used to create simple smart tags using XML files. (7 printed pages)

Download odc_mostl.exe. This download includes the MOSTL schema file in XSD format along with a sample smart tag list file instance.

Contents

Introduction
The Smart Tag XML Schema
Explaining the Smart Tag XML Schema Syntax
Sample XML Smart Tag List
Validating a Smart Tag List
Conclusion

Introduction

Smart tags are a powerful new feature in Microsoft Word 2002, Microsoft Excel 2002, and Microsoft Outlook® 2002 (when Word is enabled as the e-mail editor). With this feature, developers can create custom solutions to label specific text with relevant contextual actions. For example, a developer might wish to tag alphanumeric strings corresponding to product codes with the ability to look up inventory or sales information on that particular product.

Many solutions, such as the example above, do not require access to the full capability of the smart tag interface. To address this, Microsoft Office Smart Tag Lists (MOSTL) allow developers to create simple smart tags which recognize text strings and allow the user to open associated websites in the browser window. These smart tags are built by creating a simple Extensible Markup Language (XML) text file.

The Smart Tag XML Schema

Although using text files to create simple smart tags greatly simplifies the development process, it becomes essential to understand the definition of a valid XML file, in order to ensure that these smart tag solutions will operate correctly. The syntax which defines a valid smart tag XML file is known as the MOSTL XML schema. This schema file defines the order of the elements which a smart tag list must contain, as well as their expected content type (Boolean, String, and so on). Explaining the XML format is beyond the scope of this article; for more information on XML, see the MSDN Online XML Developer Center.

Explaining the Smart Tag XML Schema Syntax

The XML schema for smart tag lists consists of the following information:

  • Information regarding the name and description of the smart tag solution.
  • Information regarding the ability of this smart tag to be auto-updated.
  • Information on particular smart tags which this recognizer defines.

If we break down our schema syntax into these categories, we can gain a clear insight into exactly how a well-formed MOSTL file should be created. Following that, we will observe a sample MOSTL XML document.

The Root Element

All well-formed XML files contain one or more root elements, within which the data for that XML file is contained. The root element must also define the XML namespace which it and its child elements belong to. By doing this, we are able to identify within the XML that the data contained in this element pertains to the MOSTL smart tag interface.

Table 1. Smart Tag Root Element

Element Name Element Content Required? Detailed Description
smarttaglist Contains other XML elements. Yes The root element for a smart tag list definition. An attribute on this element defines its contents as pertaining to the MOSTL namespace.

Name and Description Elements

These elements are used to provide a name for your new smart tag, as well as to identify it to the user and the host application. These elements are direct children of the root element.

Table 2. Smart Tag Description Elements

Element Name Element Content Required? Detailed Description
name Text Yes A "friendly name" which will be used to define your smart tag.
lcid A comma-separated list of integers, or an asterisk (*). Optional This defines to the host application the languages in which items in the list should be recognized. If this is not present, or the host application does not expose the current locale ID (for example, Excel) the text will be treated as language inspecific.
description Text Yes A more detailed description of the function of this smart tag.
moreinfourl Text Optional A URL where a user can find more information on this smart tag.

Auto-Update Elements

More complex smart tags have a dedicated infrastructure which allows the developer to specify how and when the client application should search for potential updates to this smart tag. In order to provide this functionality for smart tag lists, the following tags are direct children of the root element.

Table 3. Smart Tag Auto-Update Elements

Element Name Element Content Required? Detailed Description
updateable Boolean Optional, default is false. Indicates whether this smart tag is updateable.
autoupdate Boolean Optional, default is false. Indicates whether this smart tag should attempt to automatically update.
lastcheckpoint Integer Optional An integer ID indicating the last version of the recognizer which was installed. If the recognizer auto-updates, this is compared to the value on the server to determine if an update should occur, and if an update occurs, it is replaced with the new checkpoint value.
lastupdate Integer Optional A long integer representing the number of minutes since 1970 since the recognizer was last updated. It is normally initially set to zero, and updated by the update procedure.
updateurl Text Optional The URL or other location which the update procedure should check for potential updates.
updatefrequency Integer Optional, default is 10080 (one week) An integer indicating the number of minutes that should elapse between successive calls to the update URL above to check for updates.
Note   Although all the items in this section are optional, they must all be present for the updating process to function correctly.

Smart Tag Parent Element

Just as the root element of the smart tag list itself contains the data necessary for the definition of a smart tag list file as well as providing the namespace of the smart tag list interface, the smart tag parent element does so for a particular type of smart tag. It contains the information on the details of a smart tag type, as well as defining a unique namespace by which recognized terms of this type will be known. It is a direct child of the root element.

Table 4. Smart Tag Parent Element

Element Name Element Content Required? Detailed Description
smarttag Contains other XML elements (seen below). Yes The root element for a smart tag definition. An attribute on this element defines its contents with an unique namespace for this smart tag "type".

Smart Tag Definition Elements

Within a particular smart tag parent element, the following elements define the way in which our smart tag will behave.

Table 5. Smart Tag Definition Elements

Element Name Element Content Required? Detailed Description
caption Text Yes The caption to be displayed with actions for this smart tag.
terms Contains other XML elements (specifically, either termfile or termlist, see below). Yes Contains the definition of the terms recognized by this smart tag.
property Text Optional Contains a comma-delimited name and value pair to be attached to the property bag when the term is recognized.
actions Contains other XML elements (see below). Yes Contains the definition of actions available for the smart tag.

Smart Tag Term Recognizer Elements

Within a smart tag, the first component of the smart tag involves the recognition of related terms. The following tags define exactly which terms (text strings) should be recognized by this smart tag. These elements are contained within the terms element listed above.

Table 6. Smart Tag Recognizer Elements

Element Name Element Content Required? Detailed Description
termfile A single element: filename Optional (a choice between termfile and termlist is required) This element is a container for the filename tag, which tells the smart tag list the name of a binary file containing the list of recognized terms.
filename Text Optional (required if termfile is used) Contains the filename of a binary file containing the list of recognized terms.
Note   A tool to create these binary term files was not available at the time of this writing.
termlist Text Optional (a choice between termfile and termlist is required) This element contains a comma-delimited text listing of the terms which this smart tag will recognize.

Smart Tag Action Elements

The final aspect to the definition of a smart tag list involves defining the actions which will be available upon recognition of a related term. In our original example, the associated actions would allow the user to look up inventory and sales data from a Web site. The actions below reside under the actions element above.

Table 7. Smart Tag Action Elements

Element Name Element Content Required? Detailed Description
action Contains the url and caption elements (see below). Yes (multiple action elements possible) A container element for an individual action.
url Text Yes The URL which this action will open in the browser. To include the recognized text in the URL, use the {TEXT} placeholder.
caption Text Yes The caption which will be displayed to the user in association with the URL above.

Sample XML Smart Tag List

With the description of the smart tag list syntax complete, we can examine a sample list to see how these elements fit together in a typical smart tag list file. This file is also included for reference as products.xml.

<FL:smarttaglist xmlns:FL="urn:schemas-microsoft-com:smarttags:list">
   <FL:name>Amalgamated Products Smart Tag</FL:name>
   <FL:lcid>0</FL:lcid>
   <FL:description>Provides smart tag access to Amalgamated Products'
      inventory and sales information.</FL:description>
   <FL:moreinfourl>http://amalgamated.com</FL:moreinfourl>
   <FL:updateable>true</FL:updateable>
   <FL:autoupdate>true</FL:autoupdate>
   <FL:lastcheckpoint>103</FL:lastcheckpoint>
   <FL:lastupdate>17186300</FL:lastupdate>
   <FL:updateurl>http://amalgamated.com/stagupdate.xml</FL:updateurl>
   <FL:updatefrequency>20160</FL:updatefrequency>
   <FL:smarttag type="urn:amalgamated-products#products">
      <FL:caption>Amalgamated Product ID</FL:caption>
      <FL:terms>
         <FL:termlist>AZ94496, MA92231, AS10244</FL:termlist>
      </FL:terms>
      <FL:actions>
         <FL:action id="InventoryData">
            <FL:caption>Check Inventory Data</FL:caption>
            <FL:url>http://amalgamated.com/products/{TEXT}</FL:url>
         </FL:action>
         <FL:action id="SalesData">
            <FL:caption>Check Sales Data</FL:caption>
            <FL:url>http://amalgamated.com/sales/{TEXT}</FL:url>
         </FL:action>
      </FL:actions>
   </FL:smarttag>
</FL:smarttaglist>

As we can see from this example, the Amalgamated Products smart tag will work in all locales, will auto-update every two weeks, and when it recognizes any of the associated terms, will present the user options to use an internal Web site to check sales and inventory data.

Validating a Smart Tag List

Although we may have authored our sample file above carefully, following the syntax layout for smart tag lists, we still need a method to validate our XML file. Using the supplied XML schema, we can validate our document using the Microsoft Sample XML Validator. This validator will allow you to validate your XML smart tag list files against the supplied XML schema. Many other validators are available on the World Wide Web; for example, the governing body responsible for XML (the W3C) offers a Web-based validator at http://www.w3.org/2001/03/webdata/xsv. Using any of these validators, you can easily check if your smart tag list file adheres to the smart tag list syntax.

Note  Validating an XML schema will ensure that your smart tag list contains valid XML text, but does not ensure that the smart tag will work exactly as you intended, as the contents of the elements themselves are not defined by the XML schema.

Conclusion

Using the XML schema for smart tag lists that is supplied, developers can quickly check that the syntax of their smart tag list documents conforms to the definition for a valid XML list file. Many utilities exist, both supplied by Microsoft and made available on the World Wide Web, which, when supplied with the schema and a document, can automatically provide the developer with the validation status of their document.

Did you find this helpful?
(1500 characters remaining)
Thank you for your feedback
Show:
© 2014 Microsoft. All rights reserved.