Show All

# Adding Actions to Query Results

In addition to hyperlinks, formatted text, and forms, the Research task pane supports actions that transfer data from the Research task pane to the user's document. You can easily add Insert and Copy actions to your query response. You can also add custom actions through the use of smart tags.

Important The Microsoft.Search.Response.Content namespace is the only namespace that supports the actions described in this topic. For more information about the elements and attributes used to define content and actions, see Handling Queries and Microsoft.Search.Response.Content Schema Documentation.

Adding simple Copy and Insert actions

The Copy action copies information about the selected item to the Clipboard. The Insert action pastes information about the item into the user's Microsoft® Office 2003 document at the insertion point location. To specify the menu choices that you want to appear on the actions menu, add the Copy or Insert elements to the Actions node of a control. The Text element of the Copy or Insert element controls the text that appears as the menu choices on the actions menu. The Data element defines which data will be copied or inserted at the insertion point location in the document when the user selects one of the choices. These built-in actions support text data only; you must use a smart tag to insert more complex data or to take more complex actions.

The following sample query response shows simple Copy and Insert actions. It was generated by a corporate directory lookup in the Email Sample. (Note that in this sample, the Microsoft.Search.Response.Content namespace is registered at the document level with the prefix "c".)

    <c:Content revision='1'>
        <c:Text>Nancy Davolio</c:Text>
        <c:Actions>
            <c:Insert default='true'>
                <c:Text>&amp;Insert Name</c:Text>
            </c:Insert>
            <c:Copy >
                <c:Text>&amp;Copy Name</c:Text>
            </c:Copy>
            <c:Data>Nancy Davolio (nancydav)</c:Data>
        </c:Actions>
    </c:Content>

The following sample query response shows the response from a lookup of the word "cold" on a thesaurus-type research service. This sample demonstrates the use of simple actions as well as the use of the Tabular control.

    <ResponsePacket revision='1' xmlns='urn:Microsoft.Search.Response'>
        <Response domain='{85B8A264-843B-443f-96D7-CA75093CFC83}'>
            <Range id='result'>
                <Results>
                    <Content xmlns=
                        'urn:Microsoft.Search.Response.Content'
                            revision='1'>
                        <Heading collapsible=”false”>
                            <Text>cold</Text>
                            <Tabular>
                                <Record borders=”false”>
                                    <Name>chilly</Name>
                                    <Actions>
                                        <Insert />
                                        <Copy />
                                        <NewQuery query=”chilly”
                                            default='true' />
                                    </Actions>
                                </Record>
                                <Record borders=”false”>
                                    <Name>freezing</Name>
                                    <Actions>
                                        <Insert />
                                        <Copy />
                                        <NewQuery query=”freezing”
                                            default='true' />
                                    </Actions>
                                </Record>
                                <Record borders=”false”>
                                    <Name>icy</Name>
                                    <Actions>
                                        <Insert />
                                        <Copy />
                                        <NewQuery query=”icy”
                                            default='true' />
                                    </Actions>
                                </Record>
                            </Tabular>
                        </Heading>
                    </Content>
                </Results>
            </Range>
            <Status>SUCCESS</Status>
        </Response>
    </ResponsePacket>

Adding custom actions with smart tags

Note A thorough explanation of smart tags is beyond the scope of this SDK. For more information, see the Smart Tag SDK on the Microsoft Developer Network (MSDN).

In addition to the simple actions supported by the Copy and Insert elements, you can use the Custom element to add smart tag actions to the list of action choices. Since Research task pane results are dictated by the Web service, they require no client-side code to run properly. This makes a research service easy to install and maintain. However, there are times when you want to provide interaction that the Research task pane does not provide without some additional customization. A richer user experience is possible with the use of client-side smart tags.

The following example illustrates the use of smart tags in the Research task pane. These paragraphs contain an excerpt from the introduction to the IBuySpy Sample.

"This sample solution also includes an actions-only smart tag that can be installed on the client. Unlike most smart tags, it does not include or require any recognition code. The loosely coupled nature of the smart tag API allows us to create an action-only smart tag DLL that can then be distributed to a desktop. If a user uses a Research task pane that leverages a smart tag and that smart tag is not installed locally, the Research task pane continues to function normally without the smart tag actions. In addition to using custom smart tags that you might deploy, any installed smart tag can be leveraged.

"The key is to mark up the response XML from the Query interface with the following XML:

    <Custom xmlns:pn="urn:schemas-microsoft-com.office11demos.ProductAnalysis">
    <pn:ProductName ProductID="374"
    	CategoryID="15">DNTGCGHT</pn:ProductName>
    </Custom>
    </Actions>

"This snippet of XML is taken from the [IBuySpy] sample solution. It uses the <Actions><Custom> elements as defined in Research task pane SDK schema for smart tags. The Research task pane uses the namespace defined in the <Custom> element to determine which smart tag to load. It then appends the child element to create the full URI that the action smart tag responds too. Therefore, in this example, the smart tag will receive:

    urn:schemas-microsoft-com.office11demos.ProductAnalysis#ProductName

"Additionally the smart tag receives all the attributes of <pn:ProductName> (as the XML shows, this would include ProductID and CategoryId) along with the text for this element. From this point, the smart tag contains the logic for the actions to display in the actions menu along with the logic to carry out the commands for those menu items."

The value that the Research task pane passes as the Target argument to the InvokeVerb method of the smart tag's ISmartTagAction interface differs depending on which application the task pane is invoked from:

- Microsoft Office Word 2003 and Microsoft Office Excel 2003 pass a Range object.
- Microsoft Office PowerPoint® 2003, Microsoft Office Outlook® 2003, and Microsoft Office Visio® 2003 pass the Application object.
- Microsoft Office OneNote™ 2003, Microsoft Office Publisher 2003, and Microsoft Internet Explorer pass a null pointer (`Nothing`).

The smart tag's action handler can use this object in conjunction with the host application's object model to perform the desired actions at the current location in the document.

Caution In Microsoft Office 2003, smart tags have an enhancement that supports cascading action menus through the use of "`///`". This first version of the Research task pane does not support cascading smart tag action menus and does not format the actions menu correctly when "`///`" is used.

Deploying smart tags through the Research task pane

To integrate smart tag functionality with the Research task pane, the service provider can incorporate a separate setup process from within a search result. This requires the provider to build a separate setup to install the smart tags, and then expose a link to the setup from within the query results.

The Microsoft.Search.Response.Content namespace supports this process through the Custom element, which can take a URL attribute. If the service uses this attribute, the user sees a Check for More Actions… item in the actions menu. This item launches the link that runs the smart tag setup program. The service can also write a hyperlink to the smart tag setup program directly in the results pane.

We recommend installing smart tags that are intended for use in the Research task pane in a Research subfolder, under the common Smart Tag folder. For example:

    	C:\Program Files\Common Files\Microsoft Shared\Smart Tag\Research

To suppress the link to the smart tag setup program after the smart tag is installed, the smart tag setup program can write some data to the service's SourceData registry key. This data is sent to the server with each query in the Data element of the ServiceData section in the Query.Office.Context namespace. For more information, see Microsoft.Search.Query.Office.Context Schema Documentation.

Important Newly-installed smart tags normally do not become active and available for use until the host application is closed and reopened. Users who have not restarted the host application may report that your smart tag actions appear to have no effect. To activate your smart tags immediately and prevent users from experiencing this inconvenience, launch `SmartTagInstall.exe` after your smart tag setup program completes. Microsoft Office 2003 editions install this small program by default in `C:\Program Files\Common Files\Microsoft Shared\Smart Tag\`. Note that this solution does not work with Microsoft Office PowerPoint 2003; PowerPoint must be restarted before newly-installed smart tags become available for use.

©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