Customizing Office 2003 Research Services: 15 Answers to Common Issues
Mark Iverson
Douglas Laudenschlager
Microsoft Corporation
February 2005
Applies to:
Microsoft Office 2003 Editions
Summary: Read answers to common issues facing developers when customizing the Office 2003 Research Services, including tips about formatting data, scaling images, and encoding data. (7 printed pages)
Contents
Introduction
Getting Started
Using the StartAt and Count Values in the Response Namespace
Encoding Content in My Response Using HTMLEncode
Identifying Users and Tracking Logon Status
Sending Hidden Data to the Server
Using a Local Research Service
Returning Multiple Range Elements
Specifying Non-Default Fonts in the Research Task Pane
Formatting Content in Tables
Indenting Hierarchical Data in the Research Task Pane
Understanding Line Wrapping and Truncation
Scaling Images
Inserting Formatted Data into Documents
Launching Documents from the Research Task Pane
Using the Context Attribute with Smart Tags
Using Research Task Pane Smart Tags with PowerPoint
Conclusion
Introduction
Microsoft Office Research Services, one of the features of Microsoft Office 2003 Editions, allows you to search public, corporate, or subscription databases without leaving your Office application or Microsoft Internet Explorer. Hopefully you have used it and perhaps even experimented with it. If you have, some of its rich features may result in a question or two. This article addresses a few of the most frequently asked questions about Research Services. We do not answer all questions here, but we make a strong effort to address the ones we see frequently. Give it a read to learn a helpful tip or two, and perhaps we'll answer your question as well.
Do you have a question that we don't address here? Send us an e-mail message and we may include it in an update to this article.
Getting Started
The following is a list of resources to help you develop custom solutions using Research Services and the Microsoft Office System.
- Research Services Downloads
- Enhancing Office 2003 Research Services with Graphics and Fancy Fonts
- Getting Started with the Research Service Development Extras Toolkit for Office 2003 Editions
- Introduction to the Office 2003 Research Services Class Library
- Connecting to Databases Using the Office 2003 Research Service Class Library Wizard
- Building Wizard Data Provider Plug-ins for the Office 2003 Research Service Class Library
How Do I Use the StartAt and Count Values in the Response Namespace
Two of the values in the Microsoft.Search.Response namespace are StartAt and Count. They first appear when the Research service sends them to the client with the first batch of results. Do you wonder what the client does with these values? We were asked whether the client returns the same values that the Research service sent in order to maintain state or whether the client sends back an incremented StartAt, such as StartAt + Count.
StartAt and Count values apply when the Research service sends them to the client with the first batch of results. Next, the client sends new, incremented values back to the server. More specifically, when the client requests a second batch of results, the Research task pane sets the new value of StartAt to the previous value of StartAt plus the value of Count. You can use Count as your normal page size without worrying about cases where the new value of StartAt``+``Count``- 1 may exceed TotalAvailable.
Encoding Content in My Response Using HTMLEncode
You may want to encode custom content into the Research service response packet as HTML. Several people doing so have wondered about the most prudent approach to this. The answer lies in using a method, such as HTMLEncode, for all content written into the XML response packet to ensure any special characters (<, >, &, ", ',) are converted to XML-appropriate character entities (such as < > & " '). If a service is extracting information from another system (such as a database, LDAP, and so on), then such a method eliminates problems when the system return un-encoded special characters. If the service generates all the strings internally, or it knows that the external system does not return any problem characters, then there is no need to encode content.
Identifying Users and Tracking Logon Status
Sometimes the Research service is set to require a logon for customer tracking or for-pay content. A couple of questions about this scenario have been asked. One involves how to identify users after they log on. The proper way to do this is to use cookies. You can use cookies after logon to identify the user and the user's logon status. If cookies associated with a paid service are lost, the user is prompted to log on again and gets only the free previews or basic experience until an identifying cookie is re-sent by the server.
A second question involves preventing the Research task pane from re-displaying the logon screen after the user logs on. This primarily concerns those with a pay-per-transaction model because it works by requiring users to log on when they want to access premium content. Therefore, to prevent re-displaying the log on screen, consider not charging per transaction because it can be problematic.
Sending Hidden Data to the Server
If you're trying to send hidden data, such as the contents of a hidden form field, to the server, you can do it two different ways:
- You can send hidden data back to the server using a cookie.
- You can use the RequeryContext element, located in the Response namespace, to send hidden data back to the server.
Using a Local Research Service
You may be wondering if, when hosting a Research service on your local computer, you still need to use SOAP to communicate with the service. You may also need to know if you can still search the Research service when your computer is not connected to the Internet.
With regard to the first question, yes, you can only communicate with a Research service using SOAP. However, you can host a Research service on your local computer, and you do not need to be connected to the Internet to search it. Usually you need to be connected to the Internet to register a new service because the registration process checks for online status. You can work around this requirement by making the necessary registration entries manually provided you know the required values. This topic is discussed in detail in Building Office 2003 Research Services That Work Offline. For more information about local services and service registration, see the Microsoft Office Research Service Software Development Kit (SDK).
Returning Multiple Range Elements
The Microsoft.Search.Response namespace allows multiple instances of a Range element. This prompts the question: When does my Research service return multiple ranges?
The answer is that it should not return multiple ranges. The Research task pane never generates multiple ranges in its query packets, so research services responding to queries should not include multiple ranges in their responses.
Specifying Non-Default Fonts in the Research Task Pane
Many of you want to know about the possibility of changing the default font used by the Research task pane. For example, can you specify a font for the text of a heading in the Content namespace?
With a small amount of code and the use of the QueryService and StringImage classes, yes, you can. The details are too lengthy to include here. However, you can find explicit instructions for how to do this in the article Enhancing Office 2003 Research Services with Graphics and Fancy Fonts.
Formatting Content in Tables
You may want to display some data returned by your Research service in a table format. For example, a stock quote retrieved from the MSN Money Stock Quotes service would benefit from an attractive table. The question is, how to make such a table.
The answer is demonstrated here using the portion of an XML response packet from the MSN Money Stock Quotes service that lays out the table of quote information. A custom smart tag action is also shown.
<?xml version="1.0" encoding="utf-8"?>
<ResponsePacket xmlns="urn:Microsoft.Search.Response" revision="1"
providerRevision="5510">
<Response domain="{2ef9ba38-c64d-4d08-8287-eb9b2f34d0e9}"
xmlns="urn:Microsoft.Search.Response">
<QueryId>{3DC06195-A3DA-4978-9430-C4ED2E32E1C8}
</QueryId>
<Range id="result">
<Results>
<Content xmlns=
"urn:Microsoft.Search.Response.Content"
revision="1">
<P light="true">Quotes delayed at least 20 min</P>
<Heading level="1">
<Text>Microsoft Corporation (US:MSFT)</Text>
<Tabular>
<Record borders="true">
<Name bold="true"><![CDATA[Last]]></Name>
<Value bold="true">26.64</Value>
</Record>
<Record borders="true">
<Name><![CDATA[Change]]></Name>
<Value>0.11</Value>
</Record>
<Record borders="true">
<Name><![CDATA[% Change]]></Name>
<Value>0.41 %</Value>
</Record>
<Record borders="true">
<Name><![CDATA[Previous Close]]></Name>
<Value>26.53</Value>
</Record>
<Record borders="true">
<Name><![CDATA[Day's High]]></Name>
<Value>26.72</Value>
</Record>
<Record borders="true">
<Name><![CDATA[Day's Low]]></Name>
<Value>26.50</Value>
</Record>
<Record borders="true">
<Name><![CDATA[Volume]]></Name>
<Value>32,011,528</Value>
</Record>
</Tabular>
<P light="true">Financial data in USD</P>
<Line>
<Actions>
<Insert>
<Text>Insert Price</Text>
</Insert>
<Data>US:MSFT 26.64</Data>
<Custom url=
"http://microsoft.com/downloads/details.aspx? FamilyId=
D20E2CA8-9F26-4EF6-8F07-F0EF37D3D35B&displaylang=en"
xmlns:st1="urn:schemas-microsoft-com
/research/stockdata">
<st1:StockData symbol="US:MSFT"
url="http://office.microsoft.com/Research/Stock.aspx? symbols
=US:MSFT">US:MSFT</st1:StockData>
</Custom>
</Actions>
</Line>
<P bold="true">More on MSN Money:</P>
. . .
</Content>
</Results>
</Range>
<Status>SUCCESS</Status>
</Response>
</ResponsePacket>
Indenting Hierarchical Data in the Research Task Pane
Just how many levels of indentation are possible in the Research task pane? When I try to use the multiple levels of indentation to display my results, the fourth level isn't indented from the third level preceding it.
The Research task pane supports five levels of indentation—the first level is reserved for the service title, and the remaining four levels are available for use in the results that you send from your custom service. However, the fifth or last level, the fourth level that you may use in your content, is not indented further than the previous level due to the limited screen width available in the Research task pane. You can confirm that your fourth-level content is indeed a child of the third level by collapsing its parent (third-level) heading and observing that the fourth level items are hidden.
Understanding Line Wrapping and Truncation
More than a few people have observed that when you place text and a hyperlink that you want to appear together within a <Line> element, it sometimes wraps to a second line, and the text that does not fit on these two lines is truncated. This is expected behavior—mixed text and hyperlinks may not wrap as expected in the Research task pane, which is a result of a limitation of the current display interface.
Scaling Images
A source of a few questions is how the Research task pane sizes and scales images that display in the task pane.
The task pane scales images in a different manner than Internet Explorer. The browser relies on screen resolution of 96 pixels per inch. Therefore, a 200-pixel x 100-pixel image displays in the browser as approximately 2.08 inches x 1.04 inches. The Research task pane, in contrast, relies on the native resolution at which the image was saved. This metadata is stored within the image file itself. For example, if the 200-pixel x 100-pixel image was saved at 400 x 200 resolution, then it displays as a half-inch square in the Research task pane.
Inserting Formatted Data into Documents
To insert formatted data from the Research task pane into your document, there's one important thing to know: You must use a smart tag action to insert formatted data from the Research task pane into an Office document.
Launching Documents from the Research Task Pane
It is not uncommon to want to open an Office document from the Research task pane, and several people have asked how to do this.
To do this, simply display a hyperlink to the file location. Remember that the user may see security warnings about opening a file or running an application.
Alternatively, you can use a custom action with a smart tag. However, when you click the link to an Office document, the document may open in Internet Explorer instead of its native application. Users who want to modify this behavior need to change a registry entry as explained in Knowledge Base article 162059—How to Configure Internet Explorer to Open Office Documents in the Appropriate Office Program Instead of in Internet Explorer.
Using the Context Attribute with Smart Tags
You may know that the context attribute can allow you to use the same smart tag to work with data in both the Research task pane and the main Office document. The following section describes how to do this:
Consider a smart tag that is triggered by the following XML returned from the server and displayed in the Research task pane:
<StockData xmlns="stockinfo"><Company>Microsoft</Company></StockData>
This smart tag can perform actions in the Research task pane by inserting data into the document and inside the document itself, for example, by changing the appearance of the data. You want to code both actions within a single smart tag.
When the smart tag inserts into the document the XML data that was passed to it, it adds the context attribute. This enables it to distinguish between XML passed by the document and XML passed by the Research task pane, because all other parameters are the same.
<StockData xmlns="stockinfo" context="doc"><Company>Microsoft</Company></StockData>
You can describe the processing logic used by the smart tag as follows:
- If @context does not exist,
- Assume the data is being passed by the Research task pane.
- Offer the action to insert the data.
- When inserting the data into the document, add the @context attribute and set it to "doc."
- Else If @context is set to "doc,"
- Offer the action to change/refresh the data.
- Be sure to preserve the @context attribute.
Using Research Task Pane Smart Tags with PowerPoint
If you attempt to use a smart tag with the Research task pane, remember that the Research task pane passes an Application pointer to smart tags when in Microsoft Office PowerPoint 2003, not a Range pointer, which it passes when in Microsoft Office Word 2003 or Microsoft Office Excel 2003. For this reason, your smart tag that works in Word and Excel does not work in PowerPoint.
Conclusion
Research Services offers a rich and flexible variety of options for customization. Often you can incorporate other technology, such as smart tags. By combining Research Services with compatible technology, the possibilities increase dramatically. You can format data in tables, insert formatted data into your document, or launch documents from the Research task pane.
This article reviews some of the common issues faced when building custom solutions with Research Services. Do you have a question that we don't address here? Send us an e-mail message and we may include it in an update to this article.