In Chapter 6, “Using external XML data in documents”, on page 114 we learned about Worldwide Widget’s award-winning customer service program. The company prides itself on how quickly it responds to a customer complaint with a sincere personalized form letter. It decides to build a smart document solution to improve response time and the sincerity of the generated content.

We can add a variety of functions to the task pane, which will allow the user to:

A working customer letter example named LetterSample.doc can be found in the example files on the book’s website.

Word documents and templates, and Excel workbooks, have to be associated with smart document solutions much like they need to be associated with schemas. Every smart document solution has a manifest, which is an XML document that lists all the components of the solution and their locations. We will look more closely at manifests in 14.4, “XML expansion packs and manifests”, on page 346.

To associate a smart document solution with a Word document:

Attaching the manifest not only associated the smart document solution with your document, it associated a schema (which is listed in the manifest) with your document. You can now use the example to test out the capabilities of smart documents.

The smart document solution is sensitive to element types. Whenever the mouse is clicked within an element, the Document Actions task pane displays user controls that are associated with that element type.

In Figure 14-1, for example, the cursor is currently positioned in the salutation element, which is associated with the radio button group at the bottom of the task pane. The four controls above that – help text, a hyperlink, etc. – belong to the ancestors of the current element, since the click occurred within them as well.

In this case there are two ancestors – greeting and letter – but all four of the other controls belong to letter.

Each of the two element types has a caption that introduces its controls. The caption for letter is “Writing a customer letter”, while the caption for salutation is “Salutation”.

The controls themselves may have captions and internal text. The caption for the radio group is “Select a salutation”. Its internal text appears next to each of the buttons.

If the user interacts with a control, a behavior will occur. In our example, if a radio button is clicked, its text will be inserted into the document as the content of the salutation.

In order for the smart document processing to accomplish these things, your solution must provide it with the necessary information. Specifically:

Tip

If you are able to limit your solution to using only hyperlink, separator, label, image, embedded help, and button controls (with buttons limited to hyperlink actions), you can provide this information in XML without writing any program code. The Smart Documents SDK has the details on this. It is an extension of the smart tags list that we discuss in 14.2.1, “Using smart tag lists (MOSTL)”, on page 338.

The code for the letter solution is written in Visual Basic 6.0.^[3] The Visual Basic project can be found in the example file LetterSample.vbp. It consists of a single class file, clsActions.cls, that is used to make LetterSample.dll.

The class implements the properties and methods of the ISmartDocument interface.^[4] The interface has eight properties of element types and controls, and 17 methods for initializing controls and responding to interactions, as follows:

element-type properties

control properties

control rendering methods

control action methods

The number of properties and methods that your class needs to implement depends on the types of control you use. In the following sections we will see how our example class implements these properties and methods.^[6]

Element-type properties

The beginning of the class code is shown in Example 14-1. The third line defines the constant cTYPES to be the number of element types with associated controls. Office gets this value from the SmartDocXmlTypeCount property. It is the basis for initializing the other element-type properties.

Example 14-1. Defining constants for later reference

Option Explicit
Implements ISmartDocument
Const cTYPES As Integer = 10

Const cNAMESPACE As String = "http://xmlinoffice.com/letter"

Const cLETTER As String = cNAMESPACE & "#letter"
Const cDATE2 As String = cNAMESPACE & "#date"
Const cADDRESS As String = cNAMESPACE & "#address"
Const cSALUTATION As String = cNAMESPACE & "#salutation"
Const cCUSTOMER As String = cNAMESPACE & "#customer"
Const cBODY As String = cNAMESPACE & "#body"
Const cP As String = cNAMESPACE & "#p"
Const cFORMAT As String = cNAMESPACE & "#format"
Const cPROBLEM As String = cNAMESPACE & "#problem"
Const cEMP As String = cNAMESPACE & "#emp"

Element-type names

The smart document interface requires element-type names to be name-space-qualified. In XML that would mean declaring a namespace abbreviation and prefixing it with a colon to the element-type name. Smart document code doesn’t have XML’s syntactic constraints and doesn’t need the abbreviation; the prefix is the complete namespace URI and a pound sign.^[7]

In the code, the namespace URI is assigned to the constant cNAMESPACE, which is used to construct the qualified names for the ten element types that are to have controls associated with them (e.g. cLETTER, cSALUTATION).

At this point, Office knows the number of element types that have controls, but not the element-type names. The property in Example 14-2 provides the names.

Example 14-2. Get the relevant element-type names

Private Property Get
ISmartDocument_SmartDocXMLTypeName
  (ByVal SmartDocID As Long) As String

  Select Case SmartDocID
    Case 1
      ISmartDocument_SmartDocXMLTypeName = cEMP
    Case 2
      ISmartDocument_SmartDocXMLTypeName = cADDRESS
    Case 3
      ISmartDocument_SmartDocXMLTypeName = cLETTER
    'REST OF THE CASES GO HERE
    Case Else
  End Select
End Property

Tip

When you implement this property, you are in effect assigning sequential numeric IDs to the element types. Be sure to create a case for each element type that has associated controls. Any order is acceptable.

Element-type captions

Each element type has a caption, which is displayed before all the controls for that element type. In Figure 14-1, the caption for the salutation element type is Salutation.

Office gets the captions from the property in Example 14-3, which functions the same way as the previous example.

Example 14-3. Get the element-type captions

Private Property Get ISmartDocument_SmartDocXMLTypeCaption
  (ByVal SmartDocID As Long, ByVal LocaleID As Long) As String

  Select Case SmartDocID
    Case 1
      ISmartDocument_SmartDocXMLTypeCaption = "Employee Name"
    Case 2
      ISmartDocument_SmartDocXMLTypeCaption = "Look up address"
    Case 3
      ISmartDocument_SmartDocXMLTypeCaption = _
      "Writing a customer letter"
    'REST OF THE CASES GO HERE
    Case Else
  End Select
End Property

Tip

Make sure the case numbers for the captions are the same as the case numbers for the corresponding element-type names in the previous example.

The LocaleID parameter indicates the location in which the code is running. You can use conditional logic with it to localize the captions.

Control count

In order to determine the control IDs for an element-type, Office needs to know how many controls there are. It uses the property in Example 14-4 to get the control count. For example, as we saw in 14.1.3, “How smart documents work”, on page 326, letter has four controls.

Example 14-4. Get the control count for an element type

Private Property Get ISmartDocument_ControlCount
  (ByVal SmartDocName As String) As Long

  Select Case SmartDocName
    Case cEMP
      ISmartDocument_ControlCount = 1
    Case cADDRESS
      ISmartDocument_ControlCount = 1
    Case cLETTER
      ISmartDocument_ControlCount = 4
    'REST OF THE CASES GO HERE
    Case Else
  End Select
End Property

Tip

When you implement this property, be sure to supply the correct quantity for each element type. Note that the argument is the element-type name (SmartDocName), not the numeric ID as in the previous examples.

Private Property Get ISmartDocument_ControlID
 (ByVal SmartDocName As String, ByVal ControlIndex As Long) As Long

  Select Case SmartDocName
    Case cEMP
      ISmartDocument_ControlID = ControlIndex
    Case cADDRESS
      ISmartDocument_ControlID = ControlIndex + 100
    Case cLETTER
      ISmartDocument_ControlID = ControlIndex + 200
    'REST OF THE CASES GO HERE
    Case Else
  End Select
End Property

Private Property Get ISmartDocument_ControlTypeFromID
 (ByVal ControlID As Long, ByVal ApplicationName As String,
  ByVal LocaleID As Long) As SmartTagLib.C_TYPE

 Select Case ControlID
   Case 1
     ISmartDocument_ControlTypeFromID = C_TYPE_TEXTBOX
   Case 101
     ISmartDocument_ControlTypeFromID = C_TYPE_BUTTON
   Case 201
     ISmartDocument_ControlTypeFromID = C_TYPE_HELP
   Case 202
     ISmartDocument_ControlTypeFromID = C_TYPE_LABEL
   'REST OF THE CASES GO HERE
   Case Else
 End Select
End Property

Private Property Get ISmartDocument_ControlCaptionFromID
  (ByVal ControlID As Long, ByVal ApplicationName As String,
  ByVal LocaleID As Long, ByVal Text As String,
  ByVal Xml As String, ByVal Target As Object) As String

  Select Case ControlID
    Case 1
      ISmartDocument_ControlCaptionFromID = _
          "Please enter your name:"
    Case 101
      ISmartDocument_ControlCaptionFromID = _
          "Look up address"
    Case 201
      ISmartDocument_ControlCaptionFromID = _
          "Overview"
    Case 202
      ISmartDocument_ControlCaptionFromID = _
          "Please see below for context-specific help, " + _
          "or follow this link to the Intranet"
    'REST OF THE CASES GO HERE
    Case Else
  End Select
End Property

Private Sub ISmartDocument_PopulateRadioGroup
  (ByVal ControlID As Long, ByVal ApplicationName As String,
   ByVal LocaleID As Long, ByVal Text As String,
   ByVal Xml As String, ByVal Target As Object,
   ByVal Props As SmartTagLib.ISmartDocProperties,
   List() As String, Count As Long, InitialSelected As Long)

    Select Case ControlID
        Case 401
            ReDim List(1 To 3) As String
            Count = 3
            List(1) = "letter"
            List(2) = "e-mail"
            List(3) = "phone call"
            InitialSelected = -1
        Case 501
            ReDim List(1 To 4) As String
            Count = 4
            List(1) = "Mr."
            List(2) = "Ms."
            List(3) = "Mrs."
            List(4) = "Dr."
            InitialSelected = -1
    End Select
End Sub

With Props
        .Write Key:="FontFace", Value:="Arial"
        .Write Key:="FontWeight", Value:="bold"
        .Write Key:="Align", Value:="left"
End With

Private Sub ISmartDocument_OnRadioGroupSelectChange
  (ByVal ControlID As Long, ByVal Target As Object,
   ByVal Selected As Long, ByVal Value As String)

  Dim objRange As Word.Range
  Set objRange = Target.XMLNodes(1).Range
  objRange.Text = Value
  Set objRange = Nothing
End Sub

The simplest way to implement smart tags is by creating an XML document that complies with the Microsoft Office Smart Tag Lists (MOSTL) schema. This document lists the text strings or patterns to look for, and the actions to show in the context menu when a smart tag is recognized.

An example of a MOSTL document for recognizing ZIP codes is shown in Example 14-11. While some MOSTL documents list literal text strings to recognize, this document specifies a pattern. The regular expression (d{5}), which represents five digits, is the content of the exp element. This means that any five consecutive digits will be recognized as a ZIP Codes smart tag.

<FL:smarttaglist
    xmlns:FL="urn:schemas-microsoft-com:smarttags:list">
  <FL:name>ZIP Codes</FL:name>
  <FL:lcid>1033</FL:lcid>
  <FL:description>Recognizes ZIP codes</FL:description>
  <FL:moreinfourl>http://xmlinoffice.com</FL:moreinfourl>

  <FL:smarttag
type="urn:schemas-microsoft-com:smarttags#msproducts">
    <FL:caption>ZIP Code</FL:caption>
    <FL:re>
       <FL:exp>(d{5})</FL:exp>
    </FL:re>
    <FL:actions>
       <FL:action id="ship">
          <FL:caption>Look up shipping rates</FL:caption>
          <FL:url>http://xmlinoffice.com/ship/{TEXT}</FL:url>
       </FL:action>
       <FL:action id="tz">
          <FL:caption>Determine time zone</FL:caption>
          <FL:url>http://xmlinoffice.com/tz/{TEXT}</FL:url>
       </FL:action>
    </FL:actions>
  </FL:smarttag>
</FL:smarttaglist>

Each menu item is specified with an action element that contains a caption (the text that will appear on the menu) and a url that is referenced when you click the menu item. Our example might allow users to look up shipping rates to that ZIP code, or to determine the time zone of the ZIP code. The expression {TEXT} is used within the URL to mean that the recognized string (in this case the 5-digit number) will be included in the URL at that point.

Implementing this smart tag list is a simple matter of placing the XML document in your local smart tag lists directory, and restarting all smart-tag-compliant applications. The directory path is normally: Program FilesCommon FilesMicrosoft SharedSmart TagLists

Smart tags can also be implemented using program code, written with either Visual Studio.NET or Visual Studio 6.0.

While MOSTL documents can only specify actions as URLs, program code allows you to perform almost any action you can imagine. You can access Web services and databases, send emails, and insert or edit text or XML elements, among other things.

More sophisticated recognizers can also be written using program code, for example to only recognize valid ZIP codes, or only ZIP codes that appear in certain areas of a document.

Unlike smart documents, smart tags have no direct relationship with the Office features that allow the editing and viewing of XML documents. Smart tags can therefore be used in any Word and Excel documents, regardless of whether the documents are associated with a schema. Smart tags can also be used in PowerPoint, Access, Outlook, and Internet Explorer.

However, in Word and Excel documents that are associated with a schema, it can be useful to create smart tag solutions that are sensitive to the XML context. For example, you could write a smart tag recognizer that only recognizes ZIP codes when they appear inside a ZIP element, or client codes when they appear inside a billTo element.

A smart tag recognizer could be written to respond when a user types the word “problem” into the body element of a letter. The context menu could allow a choice among different canned “problem letter” phrases, which would be inserted automatically into the document.

Tip

Additional information about smart tags is included in the Smart Tags SDK, which can be downloaded from the Microsoft website.

A number of research services are provided with Office 2003. These include dictionaries, thesauri, encyclopedias, language translators, Web searches, and stock quotes. The complete list can be viewed by clicking Research options on the task pane, which brings up the Research Options dialog shown in Figure 14-7.

Figure 14-7. The Research Options dialog

There are additional research services written by third parties that can be added to Office, sometimes for a fee. These services can be found on the Office Marketplace Web site, which can be accessed from the task pane by clicking Get services from Office Marketplace. To add to your available services, click Add services on the Research Options dialog and enter the URL provided by the research service documentation.

You can also write your own research service by implementing it as a SOAP Web service. While the term “research” usually implies accessing public reference sources, the research pane can be used for any information that a user might want to look up.

For example, you could develop a private company-only research service that returns background information on a customer in response to a query using its name or customer number. This would be useful to customer service representatives who are writing letters.

Research services are implemented as SOAP Web services that are specifically designed to work with the Office research pane. The Web services have two operations: Registration and Query. The Registration operation is performed when a user first adds the research service in Office. The Query operation is performed each time the user looks something up using that service.

A number of parameters may be passed to the Query operation, such as the search text, the preferred language, and the maximum number of items to retrieve. An example of an XML document that might be passed to the Web service is shown in Example 14-12.

<QueryPacket xmlns="urn:Microsoft.Search.Query"
             revision="1" build="(11.0.5308)">
  <Query>
    <SupportedFormats>
      <Format revision="1">
urn:Microsoft.Search.Response.Document:Document</Format>
    </SupportedFormats>
    <Context>
      <QueryText type="STRING" language="en-us">just-in-time
widget manufacturing</QueryText>
      <LanguagePreference>en-us</LanguagePreference>
    </Context>
  </Query>
</QueryPacket>

The research service returns an XML document with the results. The results can be rendered using a variety of techniques, including rich text, images, tables, hyperlinks, horizontal lines, collapsible sections, and even smart tags. An example of the result XML is shown in Example 14-13.^[8]

<ResponsePacket revision="1" xmlns="urn:Microsoft.Search.Response">
  <Response>
    <Range>
      <StartAt>1</StartAt>
      <Count>2</Count>
      <TotalAvailable>738</TotalAvailable>
      <Results>
        <Content xmlns="urn:Microsoft.Search.Response.Content">
          <Image source="http://www.elibrary.com/Logo.gif"/>
          <Heading collapsible="true">
            <Text>Continuous flow manufacturing...</Text>
            <P>Microwave Journal... </P>
            <Hyperlink url="http://ask.elibrary.com/login.asp...">
              <Text>Read now ...</Text>
            </Hyperlink>
          </Heading>
          <Heading collapsible="true">
            <Text>Executives try to balance...</Text>
            <!-- etc. -->
          </Heading>
        </Content>
      </Results>
    </Range>
    <Status>SUCCESS</Status>
  </Response>
</ResponsePacket>

Tip

For more information on developing custom research services, download the Office Research SDK from the Microsoft website. It provides detailed specifications for the Web services, as well as a number of examples.