Show All

# Research Service Sample Walkthrough

The IBuySpy Sample included with this SDK is a good example of a research service written with Microsoft® Visual Basic® .NET that observes the coding practices suggested in Building a Research Web Service. This sample not only displays formatted content in the Research task pane from the Response.Content and the Response.Form namespaces, but it also enhances the query results with custom actions implemented in a smart tag DLL. In this topic, we take a look at the IBuySpy sample and some of the techniques it uses to achieve powerful results in the Research task pane.

Important Since the IBuySpy sample includes complete source code, this topic includes only limited excerpts from the code. The excerpts that are shown may omit variable declarations, error handling, and other important sections of the code. We suggest that you set up the IBuySpy sample and open it in Microsoft Visual Studio® .NET so that you can follow along during this walkthrough. Note that the `Utils` class referenced in the code samples in this topic is a helper class of support functions in the IBuySpy sample.

Registration method

When a client computer calls the Registration Web method of the IBuySpy sample, the Registration method takes the following steps to assemble the registration response packet:

1. The Registration method loads the contents of a saved XML template file (RegistrationResponse.xml) into a new XMLDocument.

       Dim xdResponse As New XmlDocument
       Try
           xdResponse.Load(Utils.GetCurrentPath & _
                "\xml\RegistrationResponse.xml")
           Dim nsm As New XmlNamespaceManager(xdResponse.NameTable)
           nsm.AddNamespace("ns", _
               "urn:Microsoft.Search.Registration.Response")
           ...

   This template file contains a registration response consisting largely of empty tags. The empty template file looks like this:

       <?xml version="1.0" encoding="utf-8"?>
       <ProviderUpdate xmlns="urn:Microsoft.Search.Registration.Response">
           <Status>SUCCESS</Status>
           <Providers>
               <Provider>
                   <Message/>
                   <Id>{5A1AAF54-87F0-4f1d-A2D4-AB3E5D080DE1}</Id>
                   <Name/>
                   <QueryPath/>
                   <RegistrationPath/>
                   <Type>SOAP</Type>
                   <Services>
                       <Service>
                           <Id>{1698075D-E2F5-4254-87B2-7FC9E9AB0780}</Id>
                           <Name/>
                           <Description/>
                           <Copyright>
                               All content Copyright (c) 2003.
                           </Copyright>
                           <Display>On</Display>
                           <Category/>
                       </Service>
                   </Services>
               </Provider>
           </Providers>
       </ProviderUpdate>

2. The Registration method uses an OleDbDataReader to load the values for the registration response from the ResearchPane table of the sample's DemoData.mdb Microsoft Jet database.

       Dim oDR As OleDbDataReader = Utils.GetData_RegistrationInformation()
       oDR.Read()

3. The Registration method moves through the list of values returned by the OleDbDataReader and uses the SelectSingleNode method of the XmlDocument to locate the appropriate node for each value and copy it from the OleDbDataReader column to the InnerText property of the node.

       With xdResponse
           .SelectSingleNode("//ns:Message", nsm).InnerText = _
               oDR("ProviderMessage")
           ...
           .SelectSingleNode("//ns:Service/ns:Category", nsm).InnerText = _
               oDR("ServiceCategory")
       End With

4. The Registration method returns the string contents of the completed XmlDocument to the client computer.

       Return xdResponse.InnerXml.ToString

   The completed registration response template now looks like this:

       <?xml version="1.0" encoding="utf-8"?>
       <ProviderUpdate xmlns="urn:Microsoft.Search.Registration.Response">
           <Status>SUCCESS</Status>
           <Providers>
               <Provider>
                   <Message>
                       Congratulations ... our broad product line.
                   </Message>
                   <Id>{5A1AAF54-87F0-4f1d-A2D4-AB3E5D080DE1}</Id>
                   <Name>IBuySpyStore.com Research Pane</Name>
                   <QueryPath>
                       http://servername/IBuySpyResearchPane/Query.asmx
                   </QueryPath>
                   <RegistrationPath>
                       http://servername/IBuySpyResearchPane/
                       Registration.asmx
                   </RegistrationPath>
                   <Type>SOAP</Type>
                   <Services>
                       <Service>
                           <Id>
                               {1698075D-E2F5-4254-87B2-7FC9E9AB0780}
                           </Id>
                           <Name>IBuySpy.com Product Information</Name>
                           <Description>
                               Congratulations ... our broad product line.
                           </Description>
                           <Copyright>
                               All content Copyright (c) 2003.
                           </Copyright>
                           <Display>On</Display>
                           <Category>INTRANET_GENERAL</Category>
                       </Service>
                   </Services>
               </Provider>
           </Providers>
       </ProviderUpdate>

Query method: Introduction

When a client computer calls the Query Web method of the IBuySpy sample, the Query method takes the following steps to begin processing the query response packet:

1. First, the method loads the contents of the input argument (`queryXml`) into a new XmlDocument and references the appropriate namespaces. (The sample code does not reference the Microsoft.Search.Query.Office.Keywords namespace since it does not use the contents of the Keywords section of the query packet.)

       Dim requestXml As New XmlDocument()
       ...
       requestXml.LoadXml(queryXml)
       Dim nsmRequest As New XmlNamespaceManager(requestXml.NameTable)
       With nsmRequest
           .AddNamespace("ns", "urn:Microsoft.Search.Query")
           .AddNamespace("sp", _
               "urn:Microsoft.Search.Office.ServiceParameters")
           .AddNamespace("oc", "urn:Microsoft.Search.Query.Office.Context")
       End With

2. Next, the Query method extracts the text of the user's query and the name of the Microsoft Office host application.

       queryTerm = requestXml.SelectSingleNode("//ns:QueryText", _
           nsmRequest).InnerText
       applicationName = requestXml.SelectSingleNode("//oc:Name", _
           nsmRequest).InnerText

3. Then the Query method loads the contents of a saved XML template file (ResponsePacketWrapper.xml) into a new XmlDocument.

       responseWrapper.Load(Utils.GetCurrentPath & _
           "\xml\ResponsePacketWrapper.xml")
       Dim nsmResponseWrapper As New _
           XmlNamespaceManager(responseWrapper.NameTable)
       nsmResponseWrapper.AddNamespace( _
           "ns", "urn:Microsoft.Search.Response")

   This template file contains a query response consisting largely of empty tags. The rest of the code in the Query method and in its supporting methods fills in the Results element of the template. The empty template file looks like this:

       <?xml version="1.0" encoding="utf-8"?>
       <ResponsePacket revision="1" xmlns="urn:Microsoft.Search.Response">
           <Response domain="{1698075D-E2F5-4254-87B2-7FC9E9AB0780}">
               <QueryId>{8E823A74-053D-4434-A67B-D1CD050B3349}</QueryId>
               <Range>
                   <Results>
                   </Results>
               </Range>
               <Status>SUCCESS</Status>
           </Response>
       </ResponsePacket>

4. Finally, the Query method uses an `If/ElseIf` block to determine what type of query the user has submitted, and to call the appropriate one of six private methods (whose names begin with the `Response_` prefix) that process specific query types such as Product Details and Products by Category. After the helper method returns its results, the Query method adds these results to the query response template and returns the string contents of the completed XmlDocument to the client computer.

       responseWrapper.SelectSingleNode("//ns:Results", _
           nsmResponseWrapper).InnerXml = responseBody.ToString

       Return responseWrapper.InnerXml.ToString

In the following sections, we take a look at six different query scenarios in the IBuySpy sample. For each query scenario, we examine:

1. The steps to follow in Microsoft Office Word 2003 to launch the query.
2. The visual results of the query in the Research task pane.
3. The important portions of the XML query request packet sent from the Research task pane to the research service.
4. The important portions of the research service code that processes the query.
5. The important portions of the XML query response packet returned by the research service to the Research task pane.

Query method: Keyword search (no results found)

This section demonstrates a keyword search query that does not return results and calls the `Response_NoResults` private method in the IBuySpy sample.

1. Steps. To view the results of a keyword search that does not return results:
   1. Open CustomerLetter.doc (included with the IBuySpy sample) in Microsoft Office Word 2003.
   2. Open the Research task pane and select the IBuySpy.com Product Information service to search.
   3. While holding down the ALT key, click a word in the body of the letter that is not likely to produce product database results, such as "customers."
2. Visual Results. This query displays the following results in the Research task pane:

   Figure 1. The results of a keyword search (no results found) query in the Research task pane

3. Query Request. Here is the complete text of the query request sent to the IBuySpy.com Product Information research service. (In subsequent sections, we will show only important portions of the query packet.) The query text consists of the word "customers."

       <QueryPacket xmlns='urn:Microsoft.Search.Query'
           revision='1' build='(11.0.5606)' >
           <Query domain='{1698075D-E2F5-4254-87B2-7FC9E9AB0780}'>
               <QueryId>{D07E5132-4981-4D74-AE3D-BE7280BB5CE2}</QueryId>
               <OriginatorId>
                   {F6FF7BE0-F39C-4ddc-A7D0-09A4C6C647A5}
               </OriginatorId>
               <SupportedFormats>
                   <Format revision='1'>
                       urn:Microsoft.Search.Response.Document:Document
                   </Format>
                   <Format revision='1'>
                       urn:Microsoft.Search.Response.Content:Content
                   </Format>
                   <Format revision='1'>
                       urn:Microsoft.Search.Response.Form:Form
                   </Format>
               </SupportedFormats>
               <Context>
                   <QueryText type='STRING' language='en-us' >
                       customers
                   </QueryText>
                   <LanguagePreference>en-us</LanguagePreference>
                   <Requery></Requery>
               </Context>
               <Range id='result'></Range>
               <OfficeContext
                   xmlns='urn:Microsoft.Search.Query.Office.Context'
                   revision='1'>
                   <UserPreferences>
                       <ParentalControl>false</ParentalControl>
                   </UserPreferences>
                   <ServiceData></ServiceData>
                   <ApplicationContext>
                       <Name>Microsoft Office Word</Name>
                       <Version>(11.0.5606)</Version>
                       <SystemInformation>
                           <SkuLanguage>en-us</SkuLanguage>
                           <LanguagePack>en-us</LanguagePack>
                           <InterfaceLanguage>en-us</InterfaceLanguage>
                           <Location>US</Location>
                       </SystemInformation>
                   </ApplicationContext>
                   <QueryLanguage>en-us</QueryLanguage>
                   <KeyboardLanguage>en-us</KeyboardLanguage>
               </OfficeContext>
               <Keywords xmlns='urn:Microsoft.Search.Query.Office.Keywords'
                   revision='1'>
                   <QueryText>customers</QueryText>
                   <Keyword>
                       <Word>customers</Word>
                   </Keyword>
               </Keywords>
           </Query>
       </QueryPacket>

4. Code. The code fails to locate the term "customers" in the IBuySpy product database. However, instead of simply returning an unhelpful "No results found" message to the user, it displays two helpful lists of searchable topics:
   - A hyperlinked list of Product Categories.
   - A collapsed, hierarchical list of hyperlinked Products by Category.
   The following code generates the nested list of Products by Category. Note that the NewQuery element allows the user to request more information by clicking a category or a product. The collapsed attribute of the Heading element allows you to conserve space while grouping results.

       With outputXmlWriter
           'Content Heading
           .WriteStartElement("Content", _
           "urn:Microsoft.Search.Response.Content")
       ...
           .WriteStartElement("Heading")
           .WriteAttributeString("collapsed", "false")
           .WriteElementString("Text", "Products By Category")
           categoryData = Utils.GetData_CategoryList()
           While categoryData.Read
               .WriteStartElement("Heading") 'Category Heading
               .WriteAttributeString("collapsed", "true")
               .WriteElementString("Text", categoryData("CategoryName"))
               productsTopData = _
                   Utils.GetData_ProductsTopList(categoryData("CategoryID"))
               While productsTopData.Read
                   'New Query to get more product details
                   .WriteStartElement("NewQuery")
                   .WriteAttributeString("query", _
                       productsTopData("ModelNumber"))
                   .WriteElementString("Text", _
                       productsTopData("ModelNumber") & " - " & _
                           productsTopData("ModelName"))
                   .WriteEndElement()
               End While
               .WriteEndElement() 'Category Heading
           End While
           .WriteEndElement() 'Heading
       ...
           .WriteEndElement() 'Content
           .Flush()
       End With

5. Query Response. Here are the important portions of the query response returned by the IBuySpy.com Product Information research service.

       <?xml version="1.0" encoding="utf-8"?>
       <ResponsePacket revision="1" xmlns="urn:Microsoft.Search.Response">
           <Response domain="{1698075D-E2F5-4254-87B2-7FC9E9AB0780}">
               <QueryId>{8E823A74-053D-4434-A67B-D1CD050B3349}</QueryId>
               <Range>
                   <Results>
                       <Content
                           xmlns="urn:Microsoft.Search.Response.Content">
                           <P>
                               The search term
                               <Char bold="true">customers</Char>
                               returned no results. The following is a
                               sample list of searchable terms:
                           </P>
                           <Heading collapsed="false">
                               <Text>Categories</Text>
                               <NewQuery query="Communications">
                                   <Text>Communications</Text>
                               </NewQuery>
                               ...
                               <NewQuery query="Travel">
                                   <Text>Travel</Text>
                               </NewQuery>
                           </Heading>
                           <Heading collapsed="false">
                               <Text>Products By Category</Text>
                               <Heading collapsed="true">
                                   <Text>Communications</Text>
                                   <NewQuery query="RED1">
                                       <Text>
                                           RED1 - Communications Device
                                       </Text>
                                   </NewQuery>
                                   ...
                                   <NewQuery query="LK4TLNT">
                                       <Text>
                                           LK4TLNT - Persuasive Pencil
                                       </Text>
                                   </NewQuery>
                               </Heading>
                               ...
                               <Heading collapsed="true">
                                   <Text>Travel</Text>
                                   <NewQuery query="LNGWADN">
                                       <Text>LNGWADN - Escape Cord</Text>
                                   </NewQuery>
                                   ...
                                   <NewQuery query="WRLD00">
                                       <Text>
                                           WRLD00 - Global
                                           Navigational System
                                       </Text>
                                   </NewQuery>
                               </Heading>
                           </Heading>
                           <NewQuery query="Advanced Product Search">
                               <Text>Advanced product search ...</Text>
                           </NewQuery>
                           <HorizontalRule />
                           <P>
                               <Char bold="true">
                                   Powered by IBuySpy.com!
                               </Char>
                           </P>
                           <P>Congratulations ... at www.IBuySpy.com.</P>
                       </Content>
                   </Results>
               </Range>
               <Status>SUCCESS</Status>
           </Response>
       </ResponsePacket>

Query method: Products by Category

This section demonstrates a Products by Category query and calls the `Response_CategoryListAsForm` and the `Response_ProductSummaryForCategory` private methods in the IBuySpy sample.

1. Steps. To view the results of a Products by Category search:
   1. Complete the preceding steps for the keyword search (no results found).
   2. Click one of the hyperlinked categories, such as "Protection," displayed in the Research task pane.
2. Visual Results. This query displays the following results in the Research task pane:

   Figure 2. The results of a Products by Category query in the Research task pane

3. Query Request. Here is the variable content from the query request sent to the IBuySpy.com Product Information research service. The query text consists of the category name, "Protection," from the NewQuery element that we clicked.

       <Context>
           <QueryText type='STRING' language='en-us' >Protection</QueryText>
           ...
       </Context>
       ...
       <Keywords
           xmlns='urn:Microsoft.Search.Query.Office.Keywords' revision='1'>
           <QueryText>Protection</QueryText>
           <Keyword>
               <Word>Protection</Word>
           </Keyword>
       </Keywords>

4. Code. The following code from the `Response_CategoryListAsForm` method generates the drop-down list of Product Categories at the top of the results by using elements from the Microsoft.Search.Response.Form namespace:

       With outputXmlWriter
           'Form Heading
           .WriteStartElement("Form", "urn:Microsoft.Search.Response.Form")

           'Root Listbox
           .WriteStartElement("Listbox")
           .WriteAttributeString("dropDown", "true")
           .WriteAttributeString("id", "ProductCategoryRequery")
           .WriteAttributeString("action", "requery")
           .WriteElementString("Text", _
               "Select a different product category: ")

           'Each category is now added to the list box
           categoryListData = Utils.GetData_CategoryList()
           While categoryListData.Read
               .WriteStartElement("Option")
               .WriteAttributeString("id", categoryListData("CategoryName"))
               If UCase(categoryListData("CategoryName")) = _
                   UCase(queryTerm) Then
                   'Default to the currently selected Category
                   .WriteAttributeString("selected", "true")
               End If
               .WriteElementString("Text", categoryListData("CategoryName"))
               .WriteEndElement()
           End While

           .WriteEndElement() 'Listbox
           .WriteEndElement() 'Form
       ...
       End With

   Next, the Response_ProductSummaryForCategory method generates a title and description for each product, its unit cost, a NewQuery element to request additional details, and the Insert and Copy actions for the actions menu, by using elements from the Microsoft.Search.Response.Content namespace.

       With outputXmlWriter
           'Content Heading
           .WriteStartElement("Content", _
               "urn:Microsoft.Search.Response.Content")
           .WriteElementString("HorizontalRule", "")
       ...
           While productsData.Read
               'Product Heading
               .WriteStartElement("Heading")
               .WriteAttributeString("collapsible", "true")

               'Product Name
               .WriteElementString("Text", productsData("ModelName"))

               'Product Details
               .WriteElementString("P", productsData("Description"))
               .WriteStartElement("P")
               .WriteStartElement("Char")
               .WriteAttributeString("bold", "true")
               .WriteString("Product Price: ")
               .WriteEndElement()
               .WriteElementString("Char", _
                   Format(productsData("UnitCost"), "Currency"))
               .WriteEndElement() 'P

               'New Query to get more product details
               .WriteStartElement("NewQuery")
               .WriteAttributeString("query", productsData("ModelNumber"))
               .WriteElementString("Text", "Product Details ...")
               .WriteEndElement()

               'Button with Actions
               .WriteStartElement("Actions")
               .WriteStartElement("Insert")
               .WriteElementString("Text", "Insert Summary")
               .WriteEndElement() 'Insert
               .WriteStartElement("Copy")
               .WriteElementString("Text", "Copy Summary")
               .WriteEndElement() 'Copy
               .WriteElementString("Data", productsData("ModelName") & _
                   " - " & productsData("Description") & _
                   " (Product Price: " & Format(productsData("UnitCost"), _
                   "Currency") & ")")
               .WriteEndElement() 'Actions

               .WriteEndElement() 'Product Heading
           End While

       ...
           .WriteEndElement() 'Content
           .Flush()

       End With

5. Query Response. Here are the important portions of the query response returned by the IBuySpy.com Product Information research service.

       <Range>
           <Results>
               <Form xmlns="urn:Microsoft.Search.Response.Form">
                   <Listbox dropDown="true" id="ProductCategoryRequery"
                       action="requery">
                       <Text>Select a different product category: </Text>
                       <Option id="Communications">
                           <Text>Communications</Text>
                       </Option>
                       ...
                       <Option id="Travel"
                           ><Text>Travel</Text>
                       </Option>
                   </Listbox>
               </Form>
               <Content xmlns="urn:Microsoft.Search.Response.Content">
                   <NewQuery query="Advanced Product Search">
                       <Text>Advanced product search ...</Text>
                   </NewQuery>
               </Content>
               <Content xmlns="urn:Microsoft.Search.Response.Content">
                   <HorizontalRule />
                   <P>
                       <Char bold="true" italic="true">
                           Products for category PROTECTION
                       </Char>
                   </P>
                   <Heading collapsed="true">
                       <Heading collapsible="true">
                           <Text>Bullet Proof Facial Tissue</Text>
                           <P>Being a spy ... stop penetration.</P>
                           <P>
                               <Char bold="true">Product Price: </Char>
                               <Char>$79.99</Char>
                           </P>
                           <NewQuery query="BSUR2DUC">
                               <Text>Product Details ...</Text>
                           </NewQuery>
                           <Actions>
                               <Insert>
                                   <Text>Insert Summary</Text>
                               </Insert>
                               <Copy>
                                   <Text>Copy Summary</Text>
                               </Copy>
                               <Data>
                                   Bullet Proof Facial Tissue ...
                                   (Product Price: $79.99)
                               </Data>
                           </Actions>
                       </Heading>
                       ...
                   </Heading>
               </Content>
           </Results>
       </Range>

Query method: Keyword search (results found)

This section demonstrates a keyword search query that returns results and calls the `Response_ProductKeywordSearch` private method in the IBuySpy sample.

1. Steps. To view the results of a keyword search that returns results from the IBuySpy database:
   1. Complete the preceding steps for the Products by Category Search.
   2. While holding down the ALT key, click the word "wallet" in the body of the letter.
2. Visual Results. This query displays the following results in the Research task pane:

   Figure 3. The results of a keyword search (results found) query in the Research task pane

3. Query Request. Here is the variable content from the query request sent to the IBuySpy.com Product Information research service. The query text consists of the word "Wallet."

       <Context>
           <QueryText type='STRING' language='en-us' >Wallet</QueryText>
           ...
       </Context>
       ...
       <Keywords xmlns='urn:Microsoft.Search.Query.Office.Keywords'
           revision='1'>
           <QueryText>Wallet</QueryText>
           <Keyword>
               <Word>Wallet</Word>
           </Keyword>
       </Keywords>

4. Code. The `Response_ProductKeywordSearch` method uses code similar to the `Response_ProductSummaryForCategory` method discussed in the preceding section to display similar product information, with a hyperlink for additional information and an actions menu.
5. Query Response. Here are the important portions of the query response returned by the IBuySpy.com Product Information research service.

       <Range>
           <Results>
               <Content xmlns="urn:Microsoft.Search.Response.Content">
                   <P>Your search returned the following results:</P>
               </Content>
               <Content xmlns="urn:Microsoft.Search.Response.Content">
                   <Heading collapsible="true" collapsed="false">
                       <Text>Counterfeit Creation Wallet</Text>
                       <P>Don't be caught ... your legal tender!</P>
                       <P>
                           <Char bold="true">Product Price: </Char>
                           <Char>$999.99</Char>
                       </P>
                       <NewQuery query="DNTGCGHT">
                           <Text>Product Details ...</Text>
                       </NewQuery>
                       <Actions>
                           <Insert>
                               <Text>Insert Summary</Text>
                           </Insert>
                           <Copy>
                               <Text>Copy Summary</Text>
                           </Copy>
                           <Data>
                               Counterfeit Creation Wallet ...
                               (Product Price: $999.99)
                           </Data>
                       </Actions>
                   </Heading>
               </Content>
               <Content xmlns="urn:Microsoft.Search.Response.Content">
                   <P>Your search returned 1 products.</P>
               </Content>
           </Results>
       </Range>

Query method: Product Details

This section demonstrates a Product Details query and calls the `Response_ProductDetails` private method in the IBuySpy sample.

1. Steps. To view the results of a Product Details search:
   1. Complete the preceding steps for the keyword search (results found).
   2. Click the Product Details hyperlink in the Research task pane.
2. Visual Results. This query displays the following results in the Research task pane:

   Figure 4. The results of a Product Details query in the Research task pane

3. Query Request. Here is the variable content from the query request sent to the IBuySpy.com Product Information research service. The query text consists of the product ID, "DNTGCGHT," which is the value of the query attribute of the NewQuery element that we clicked.

       <Context>
           <QueryText type='STRING' language='en-us' >DNTGCGHT</QueryText>
           ...
       </Context>
       ...
       <Keywords xmlns='urn:Microsoft.Search.Query.Office.Keywords'
           revision='1'>
           <QueryText>DNTGCGHT</QueryText>
           <Keyword>
               <Word>DNTGCGHT</Word>
           </Keyword>
       </Keywords>

4. Code. The `Response_ProductDetails` method displays extensive product information in the limited screen space of the task pane by making effective use of the elements of the Microsoft.Search.Response.Content namespace, including:
   - A product image.
   - Product details listed in table format by using the Tabular element.
   - An actions menu that includes custom actions made possible by a smart tag.
   - A collapsed, hyperlinked list of Related Products.
   - Horizontal lines to divide sections of the results visually.
   - A NewQuery element that invokes the Advanced Product Search form.
   The following code uses an XmlTextWriter (not shown) to generate the table of Additional Product Details:

        'Product Table of Details
       .WriteStartElement("Tabular")
       .WriteAttributeString("title", "Additional Product Details")
       'Unit Cost
       .WriteStartElement("Record")
       .WriteElementString("Name", "Unit Cost")
       .WriteElementString("Value", Format(productDetailsData("UnitCost"), _
           "Currency"))
       .WriteEndElement() 'Record
       'Units In Stock
       .WriteStartElement("Record")
       .WriteElementString("Name", "Units In Stock")
       .WriteElementString("Value", productDetailsData("UnitsInStock"))
       .WriteEndElement() 'Record
       'Product Category
       .WriteStartElement("Record")
       .WriteElementString("Name", "Product Category")
       '.WriteAttributeString("bold", "true")
       .WriteElementString("Value", productDetailsData("CategoryName"))
       .WriteStartElement("Actions")
       .WriteStartElement("NewQuery")
       .WriteAttributeString("query", productDetailsData("CategoryName"))
       .WriteElementString("Text", "View Category Details")
       .WriteEndElement() 'NewQuery
       .WriteEndElement() 'Actions
       .WriteEndElement() 'Record
       'Model Number
       .WriteStartElement("Record")
       .WriteElementString("Name", "Model Number")
       .WriteElementString("Value", productDetailsData("ModelNumber"))
       .WriteEndElement() 'Record
       .WriteEndElement() 'Tabular

   The following code uses an XmlTextWriter (not shown) to generate the menu of custom actions. Note the use of the WriteRaw method of the XmlTextWriter when concatenating a complex string of custom XML.

        Smart Tag
       If applicationName = "Microsoft Word" Or applicationName = _
           "Microsoft Excel" Or applicationName = _
               "Microsoft Office Word" Then
           .WriteStartElement("Line")
           .WriteStartElement("Actions")
           .WriteStartElement("Custom")
           .WriteAttributeString("xmlns:pn", _
               "urn:schemas-microsoft-com.office11demos.ProductAnalysis")
           .WriteRaw("<pn:ProductName ProductID='" & _
               productDetailsData("ProductID") & "' CategoryID='" & _
                   productDetailsData("CategoryID") & "'>" & _
                       productDetailsData("ModelNumber") & _
                           "</pn:ProductName>")
           .WriteEndElement()
           .WriteEndElement()
           .WriteEndElement()
       End If 'End Smart Tag

5. Query Response. Here are the important portions of the query response returned by the IBuySpy.com Product Information research service.

       <Range>
           <Results>
               <Content xmlns="urn:Microsoft.Search.Response.Content">
                   <P>
                       <Char bold="true">Counterfeit Creation Wallet</Char>
                       <Char light="true"> (DNTGCGHT)</Char>
                   </P>
                   <P>Don't be caught ... your legal tender!</P>
                   <HorizontalRule />
                   <Image source="http://servername/IBuySpyResearchPane/
                       images/DNTGCGHT.gif" />
                   <HorizontalRule />
                   <Tabular title="Additional Product Details">
                       <Record>
                           <Name>Unit Cost</Name>
                           <Value>$999.99</Value>
                       </Record>
                       <Record>
                           <Name>Units In Stock</Name>
                           <Value>10</Value>
                       </Record>
                       <Record>
                           <Name>Product Category</Name>
                           <Value>Deception</Value>
                           <Actions>
                               <NewQuery query="Deception">
                                   <Text>View Category Details</Text>
                               </NewQuery>
                           </Actions>
                       </Record>
                       <Record>
                           <Name>Model Number</Name>
                           <Value>DNTGCGHT</Value>
                       </Record>
                   </Tabular>
                   <Line>
                       <Actions>
                           <Custom xmlns:pn="urn:schemas-microsoft-com.
                               office11demos.ProductAnalysis">
                               <pn:ProductName ProductID="374"
                                   CategoryID="15">DNTGCGHT</pn:ProductName>
                           </Custom>
                       </Actions>
                   </Line>
                   <Heading collapsed="true">
                       <Text>Related Products</Text>
                       <NewQuery query="CITSME9">
                           <Text>CITSME9 - Cloaking Device</Text>
                       </NewQuery>
                       ...
                       <NewQuery query="THNKDKE1">
                               <Text>THNKDKE1 - Hologram Cufflinks</Text>
                           </NewQuery>
                   </Heading>
                   <HorizontalRule />
                   <NewQuery query="Advanced Product Search">
                       <Text>Advanced product search ...</Text>
                   </NewQuery>
               </Content>
           </Results>
       </Range>

Query method: Advanced Product Search form

This section demonstrates the Advanced Product Search form and calls the `Response_AdvancedSearchForm` private method in the IBuySpy sample.

1. Steps. To view the results of displaying the Advanced Product Search form:
   1. Complete the preceding steps for the Product Details Search.
   2. Click the Advanced product search hyperlink displayed in the Research task pane.
2. Visual Results. This query displays the following results in the Research task pane:

   Figure 5. The results of displaying the Advanced Product Search form in the Research task pane

3. Query Request. Here is the variable content from the query request sent to the IBuySpy.com Product Information research service. The query text consists of the phrase, "Advanced Product Search," from the NewQuery element that we clicked.

       <Context>
           <QueryText type='STRING' language='en-us' >
               Advanced Product Search
           </QueryText>
           ...
       </Context><Range id='result'>
       ...
       <Keywords xmlns='urn:Microsoft.Search.Query.Office.Keywords'
           revision='1'>
           <QueryText>Advanced Product Search</QueryText>
           <Keyword>
               <Word>Advanced</Word>
           </Keyword>
           <Keyword>
               <Word>Product</Word>
           </Keyword>
           <Keyword>
               <Word>Search</Word>
           </Keyword>
       </Keywords>

4. Code. The `Response_AdvancedSearchForm` method demonstrates many elements of the Microsoft.Search.Response.Form namespace, including:
   - A group of radio buttons (RadioGroup and Option elements).
   - Edit elements for minimum and maximum price. (Since the same code also processes the advanced search, it contains some input validation and code to redisplay values that have already been entered.)
   - A Checkbox element to limit the results to products that are currently in stock.
   - A Button element to launch the search. The icon attribute displays the built-in Go icon, which consists of a green button image that contains an arrow.
   The following code uses an XmlTextWriter (not shown) to generate the search form:

        'Form Heading
       .WriteStartElement("Form", "urn:Microsoft.Search.Response.Form")

       'Radio Group of Categories
       .WriteStartElement("RadioGroup")
       .WriteAttributeString("id", "AdvancedSearchRadioGroup")
       .WriteElementString("Text", "Select a Category for this search:")
       'Add an "All Categories" to the list
       .WriteStartElement("Option") 'Category Heading
       .WriteAttributeString("id", "All")
       .WriteAttributeString("selected", "true")
       .WriteElementString("Text", "All Categories")
       .WriteEndElement() 'Category Heading
       categoryData = Utils.GetData_CategoryList()
       While categoryData.Read
           .WriteStartElement("Option") 'Category Heading
           .WriteAttributeString("id", categoryData("CategoryName"))
           If categoryData("CategoryName") = category Then
               .WriteAttributeString("selected", "true")
           End If
           .WriteElementString("Text", categoryData("CategoryName"))
           .WriteEndElement() 'Category Heading
       End While
       .WriteEndElement() 'RadioGroup
       If Not categoryData Is Nothing Then
           categoryData.Close()
       End If

       'Low Price Range Edit box
       .WriteStartElement("Edit") 'Category Heading
       .WriteAttributeString("id", "AdvancedSearchEditLow")
       If lowPrice <> "" Then
           .WriteAttributeString("value", lowPrice)
       End If
       .WriteElementString("Text", "Product low price (Optional):")
       .WriteEndElement()
       If lowPrice <> "" And Not IsNumeric(lowPrice) Then
           .WriteElementString("Label", "Please provide a valid number for the Low Price.")
       End If
       'Low Price

       'High Price Range Edit box
       ...
       'High Price

       'In Stock check box
       .WriteStartElement("Checkbox") 'Category Heading
       .WriteAttributeString("id", "AdvancedSearchCheckbox")
       If inStock = True Then
           .WriteAttributeString("selected", "true")
       End If
       .WriteElementString("Text", "Only show items in stock")
       .WriteEndElement() 'Checkbox

       'Search Button
       .WriteStartElement("Button") 'Category Heading
       .WriteAttributeString("id", "AdvancedSearchButton")
       .WriteAttributeString("icon", "go")
       .WriteAttributeString("action", "requery")
       .WriteEndElement() 'Low Price

       .WriteEndElement() 'Form

5. Query Response. Here are the important portions of the query response returned by the IBuySpy.com Product Information research service.

       <Range>
           <Results>
               <Form xmlns="urn:Microsoft.Search.Response.Form">
                   <RadioGroup id="AdvancedSearchRadioGroup">
                       <Text>Select a Category for this search:</Text>
                       <Option id="All" selected="true">
                           <Text>All Categories</Text>
                       </Option>
                       <Option id="Communications">
                           <Text>Communications</Text>
                       </Option>
                       ...
                       <Option id="Travel">
                           <Text>Travel</Text>
                       </Option>
                   </RadioGroup>
                   <Edit id="AdvancedSearchEditLow">
                       <Text>Product low price (Optional):</Text>
                   </Edit>
                   <Edit id="AdvancedSearchEditHigh">
                       <Text>Product high price (Optional):</Text>
                   </Edit>
                   <Checkbox id="AdvancedSearchCheckbox">
                       <Text>Only show items in stock</Text>
                   </Checkbox>
                   <Button id="AdvancedSearchButton"
                       icon="go" action="requery" />
               </Form>
               <Content xmlns="urn:Microsoft.Search.Response.Content" />
           </Results>
       </Range>

Query method: Advanced Product Search results

This section demonstrates the results from an Advanced Product Search query and also calls the `Response_AdvancedSearchForm` private method in the IBuySpy sample.

1. Steps. To view the results of an Advanced Product Search:
   1. Complete the preceding steps for displaying the Advanced Product Search form.
   2. In the form, fill in values for low and high price, select the In stock check box, and click Go.
2. Visual Results. This query displays the following results in the Research task pane:

   Figure 6. The results of an Advanced Product Search query in the Research task pane

3. Query Request. Here is the complete text of the query request sent to the IBuySpy.com Product Information research service. The query text again consists of the phrase, "Advanced Product Search," because of the "requery" value of the action attribute of the Button element that we clicked.

       <QueryPacket xmlns='urn:Microsoft.Search.Query'
           revision='1' build='(11.0.5606)' >
           <Query domain='{1698075D-E2F5-4254-87B2-7FC9E9AB0780}'>
               <QueryId>{1529838F-8A6F-4949-92A5-39DD419D535E}</QueryId>
               <OriginatorId>
                   {F6FF7BE0-F39C-4ddc-A7D0-09A4C6C647A5}
               </OriginatorId>
               <SupportedFormats>
                   <Format revision='1'>
                       urn:Microsoft.Search.Response.Document:Document
                   </Format>
                   <Format revision='1'>
                       urn:Microsoft.Search.Response.Content:Content
                   </Format>
                   <Format revision='1'>
                       urn:Microsoft.Search.Response.Form:Form
                   </Format>
               </SupportedFormats>
               <Context>
                   <QueryText type='STRING' language='en-us' >
                       Advanced Product Search
                   </QueryText>
                   <LanguagePreference>en-us</LanguagePreference>
                   <Requery>
                       <ServiceParameters
                           xmlns=
                           'urn:Microsoft.Search.Office.ServiceParameters'>
                           <Action>AdvancedSearchButton</Action>
                           <Parameters>
                               <AdvancedSearchRadioGroup>
                                   All
                               </AdvancedSearchRadioGroup>
                               <AdvancedSearchEditLow>
                                   500
                               </AdvancedSearchEditLow>
                               <AdvancedSearchEditHigh>
                                   1500
                               </AdvancedSearchEditHigh>
                               <AdvancedSearchCheckbox/>
                           </Parameters>
                       </ServiceParameters>
                   </Requery>
               </Context>
               <Range id='result'></Range>
               <OfficeContext
                   xmlns='urn:Microsoft.Search.Query.Office.Context'
                   revision='1'>
                   <UserPreferences>
                       <ParentalControl>false</ParentalControl>
                   </UserPreferences>
                   <ServiceData></ServiceData>
                   <ApplicationContext>
                       <Name>Microsoft Office Word</Name>
                       <Version>(11.0.5606)</Version>
                       <SystemInformation>
                           <SkuLanguage>en-us</SkuLanguage>
                           <LanguagePack>en-us</LanguagePack>
                           <InterfaceLanguage>en-us</InterfaceLanguage>
                           <Location>US</Location>
                       </SystemInformation>
                   </ApplicationContext>
                   <QueryLanguage>en-us</QueryLanguage>
                   <KeyboardLanguage>en-us</KeyboardLanguage>
               </OfficeContext>
               <Keywords
                   xmlns='urn:Microsoft.Search.Query.Office.Keywords'
                   revision='1'>
                   <QueryText>Advanced Product Search</QueryText>
                   <Keyword>
                       <Word>Advanced</Word>
                   </Keyword>
                   <Keyword>
                       <Word>Product</Word>
                   </Keyword>
                   <Keyword>
                       <Word>Search</Word>
                   </Keyword>
               </Keywords>
           </Query>
       </QueryPacket>

4. Code. The code in the `Response_AdvancedSearchForm` method now regenerates the form, with the user's input displayed in the form elements, followed by a list of matching products. The following code uses an XmlTextWriter (not shown) to produce the list of records that match the search criteria:

       Dim countRecords As Integer = 0 'Track number of returned records
           If category <> "" Then
           productsData = Utils.GetData_DataProductsAdvancedSearch( _
               category, lowPrice, highPrice, inStock)
           .WriteElementString("HorizontalRule", "")
           'Each product is now listed
           While productsData.Read
               countRecords += 1
               If countRecords = 1 Then
                   .WriteElementString("P", _
                       "Your search returned the following results:")
               End If
               'Product Heading
               .WriteStartElement("P")
               .WriteStartElement("Char")
               .WriteAttributeString("bold", "true")
               .WriteString(productsData("ModelName") & ":")
               .WriteEndElement()
               'Product Details
               .WriteString(" " & Left(productsData("Description"), 80) & _
                   "....")
               .WriteEndElement() 'Product Heading
               'New Query to get more product details
               .WriteStartElement("NewQuery")
               .WriteAttributeString("query", productsData("ModelNumber"))
               .WriteElementString("Text", "Product Details ...")
               .WriteEndElement()
               '.WriteElementString("P", "")
           End While
           If countRecords = 0 Then
               'No records, throw general exception
               'will return a no result error
               Dim eTemp As Exception
               Throw eTemp
           Else
               .WriteElementString("P", "Your search returned " & _
                   countRecords & " products.")
           End If
       End If

5. Query Response. Here are the important portions of the query response returned by the IBuySpy.com Product Information research service.

       <Range>
           <Results>
               <Form xmlns="urn:Microsoft.Search.Response.Form">
                   <RadioGroup id="AdvancedSearchRadioGroup">
                       <Text>Select a Category for this search:</Text>
                       <Option id="All" selected="true">
                           <Text>All Categories</Text>
                       </Option>
                       <Option id="Communications">
                           <Text>Communications</Text>
                       </Option>
                       ...
                       <Option id="Travel">
                           <Text>Travel</Text>
                       </Option>
                   </RadioGroup>
                   <Edit id="AdvancedSearchEditLow" value="500">
                       <Text>Product low price (Optional):</Text>
                   </Edit>
                   <Edit id="AdvancedSearchEditHigh" value="1500">
                       <Text>Product high price (Optional):</Text>
                   </Edit>
                   <Checkbox id="AdvancedSearchCheckbox" selected="true">
                       <Text>Only show items in stock</Text>
                   </Checkbox>
                   <Button id="AdvancedSearchButton" icon="go"
                       action="requery" />
               </Form>
               <Content xmlns="urn:Microsoft.Search.Response.Content">
                   <HorizontalRule />
                   <P>Your search returned the following results:</P>
                   <P>
                       <Char bold="true">
                           Counterfeit Creation Wallet:
                       </Char> ...
                   </P>
                       <NewQuery query="PT109">
                           <Text>Product Details ...</Text>
                       </NewQuery>
                       ...
                       <P>
                           <Char bold="true">Rain Racer 2000:
                       </Char> ...
                    </P>
                   <NewQuery query="RU007">
                       <Text>Product Details ...</Text>
                   </NewQuery>
                   <P>Your search returned 4 products.</P>
               </Content>
           </Results>
       </Range>

©2003-2004 Microsoft Corporation. All rights reserved. Permission to copy, display and distribute this document is available at: http://msdn.microsoft.com/library/en-us/odcXMLRef/html/odcXMLRefLegalNotice.asp