Script Smart
Andrew Clinick
Microsoft Corporation
May 15, 2001
Microsoft® Office XP introduces a powerful new feature, smart tags, which allows Office applications and Microsoft® Internet Explorer to analyze the information that you are entering or viewing, and provide links to relevant information about the content. This is great for when you're writing reports or spreadsheets, and you want to be able to look up some information quickly. A good example of how Office uses smart tags is e-mail addresses. When you type in a person's name, Office will look that up in your Outlook contacts database, and if the person exists, then the smart tag enables you to click on the user name and select an option from a context menu. In this case, you can send the person an e-mail, organize a meeting, open the contact, or even insert the address of the user. Luckily, the developers of smart tags realized that developers need a way to write new smart tags, and so they provided a Smart Tag SDK. In this article I'll take a look at the Smart Tag SDK and how you can use it from a scripting perspective.
How Do Smart Tags Work?
In order to understand how to use smart tags, it's important to know how the system works. Smart tags can do two things: 1) recognize content that is sent to them, and 2) perform actions based on the content. The implementation of the "recognizer" and action is provided by a series of COM objects. Microsoft Office ships with a number of recognizers and actions by default, such as the name recognizer and action I used in my earlier example. When Word loads, it checks to see what recognizer or action add-ins are available on the system, and then ensures that these are loaded so when you start typing, any context is passed into the add-ins. The Smart Tags SDK (you can get the SDK from Microsoft Office XP Smart Tag SDK 1.1) has a good architectural diagram that shows how things work:
Figure 1. Architecture of the smart tags functionality
The components that respond to actions and recognition have to implement a particular COM interface, which would appear to rule out the use of script. Luckily, however, the smart tags solution supports a mechanism to create a smart tag via XML, which can then link to a server. This means that you can use this to link through to script running in an ASP page to do much of the work.
Smart Tag Lists
Smart tag lists provide a simple XML-based mechanism for defining a set of terms that smart tags will recognize without having to go to the trouble of implementing a complete COM component. All you need to do is create a list of terms in XML, and then create a list of actions to show whenever a term from the list is encountered. The Smart Tag list plug-in loads the XML definition whenever Microsoft® Word, Microsoft® Excel, or IE are loaded, and ensures that whenever a term from the list is encountered in a document, a menu containing all the actions is shown. The great thing about this is that the actions can link to ASP pages with context about the term.
To illustrate how you can use script to take advantage of this, I've built a Microsoft® VBScript syntax helper, for a fictional site, fabrikam.com. The list of terms is a list of keywords, functions, and statements for VBScript, and there are two actions presented to the user whenever they use the smart tag in Word, Excel, or IE: "Get Help from fabrikam.com" and "fabrikam.com is cool." The first action navigates to an ASP page, getref.asp, which will show all the relevant information about that VBScript keyword and any examples provided by fabrikam.com. The second action is a pure advertisement for fabrikam.com.
How to Implement a List
The smart tag list component gets all its information from an XML file, msotl.xml. This file contains the list of terms, the actions you want to define, and some naming information about the smart tag itself. The first thing you need to do is set the name of the smart tag list, in this case "Script Terms," and then a description of what the smart tag list is about. Once you've done this, next set the terms that will be used for the smart tag list. The XML definition provides a termlist element, which you fill with a comma-separated list of terms:
<FL:terms>
<FL:termlist>do while, setLocale, getLocale, getref, Class, function, sub, for each</FL:termlist>
</FL:terms>
In this example, I've only used a few VBScript terms to keep it simple.
Once all the terms have been defined, all that's left to do is to setup the actions that will show up when the user clicks on the smart tag. The List XML definition includes an<FL:actions>element that contains all the actions that will show up. Each action has a caption and URL that should be called when the user selects the menu item. In this example, I've added a gethelp action and a gratuitous advertisement for fabrikam.com. The gethelp action includes a URL to the getref.asp page that takes the name of the term as an argument. This is simple to achieve, since{TEXT}is substituted with the term that caused the smart tag to be invoked.
XML to define actions:
<FL:actions>
<FL:action id="Lookupdef">
<FL:caption>&Get Help from fabrikam.com</FL:caption>
<FL:url>http://www.fabrikam.com/getref.asp?String={TEXT}</FL:url>
</FL:action>
<FL:action id="CompanyInfo">
<FL:caption>&Fabrikam.com is cool</FL:caption>
<FL:url>http://www.fabrikam.com</FL:url>
</FL:action>
</FL:actions>
Figure 2. What the smart tag looks like in Word
Once all the information is entered into the msotl.xml file, all that is required is to save the file back to the appropriate location on the machine. If the list is going to be made available to all users, then save it to program files\common files\microsoft shared\smart tags\lists. If it's for a specific user, then save it to drive:\Documents and Settings\username\Application Data\Microsoft\Smart Tag Lists, which will ensure that the list can roam with the user.
Example msotl.xml:
<FL:smarttaglist xmlns:FL="urn:schemas-microsoft-com:smarttags:list">
<FL:name>Script Terms</FL:name>
<FL:lcid>1033</FL:lcid>
<FL:description>A list of Script Terms</FL:description>
<FL:moreinfourl>http://www.fabrikam.com/smarttags</FL:moreinfourl>
<FL:updateable>true</FL:updateable>
<FL:autoupdate>true</FL:autoupdate>
<FL:lastcheckpoint>100</FL:lastcheckpoint>
<FL:lastupdate>5123942</FL:lastupdate>
<FL:updateurl>http://www.fabrikam.com/smarttags/listupdate.xml</FL:updateurl>
<FL:updatefrequency>20160</FL:updatefrequency>
<FL:smarttag type="urn:schemas-fabrikam-com:script#terms">
<FL:caption>Script Help</FL:caption>
<FL:terms>
<FL:termlist>do while, setLocale, getLocale, getref, Class, function, sub, for each</FL:termlist>
</FL:terms>
<FL:actions>
<FL:action id="Lookupdef">
<FL:caption>&Get Help from Fabrikam.com</FL:caption>
<FL:url>http://www.fabrikam.com/getref.asp?String={TEXT}</FL:url>
</FL:action>
<FL:action id="CompanyInfo">
<FL:caption>&Fabrikam.com is cool</FL:caption>
<FL:url>http://www.fabrikam.com</FL:url>
</FL:action>
</FL:actions>
</FL:smarttag>
</FL:smarttaglist>
Implementing the Help ASP Page
To keep the example for this article simple, I've implemented a rudimentary help page that just returns the documentation for the particular term that help is being asked for. Ideally this would be stored in a database, and the ASP page would query the database based on the term being queried. I cheated in this example by storing the documentation in files in a subfolder, and by just loading the appropriate file for the term being queried—pretty low tech I know, but it does keep the page simple.
<%
dim strTerm
strTerm = server.mappath("\terminfo") & ("\") & Request.QueryString("string") & ".htm"
set myFSO = CreateObject("scripting.FileSystemObject")
Set ts = myFSO.OpenTextFile(strTerm)
response.write ts.readall
%>
The key to this example is that it's simple to build in links between Office smart tags and scripts running on your server. The example used here, script terms, is probably not the most useful of examples, but it illustrates the point of how you can get your information into Office. I encourage you to try out the XML-based smart tags feature and integrate it with script on the server.
As always, we look forward to hearing your feedback and ideas for making scripting easier. Please feel free to contact us at msscript@microsoft.com and to use the newsgroups on msnews.microsoft.com.