OpenSearch Gadget Contributions

Reference Implementation Demo Video:  opensearch.swf

Proposal Details

Scope of change: Medium
Reference to existing standard: concepts of search contribution are derived from the OpenSearch Standard.
Champion Name: Andrew Davis(IBM), Igor Belakoskiy(IBM)
Specification editor names: Andrew Davis(IBM), Igor Belakoskiy(IBM), looking for others?
Ref Implementors commitment: 1 developers(Igor) at IBM for 6-8 weeks

OSGS Discussion Thread

Issue Tracker

Overview

Many gadgets on a page in a container may have search functionality, which are currently limited to the gadget itself. Using the optional opensearch feature, gadgets may contribute a search source to the container. The container may then choose to implement a common UI to aggregate search results from multiple sources. Pre-loading the gadgets makes their search contributions available to the container and allows the container to display them in a search menu, when the page is rendered.

OpenSearch is the leading standard for web pages to describe to the browser and other host client applications what search capabilities are available. Conceptually gadgets could use this same definition format to notify the container that they can expose search functionality.

Use Cases

1) Joe DaUser's home page contains several open social gadgets. The user wants to find out what's been happening on baseball's opening day. He types the search string into the common search input field, and sees results back from his newspaper, twitter, and friends status update widgets appear on the page. Those gadgets all contained OpenSearch declarations, which were picked up by the container. Slightly overwhelmed by the number of results, Joe un-checks the twitter and newspaper options from the search menu, and now only sees updates from his friends. In the meanwhile, he does not see results from his MLB gadget, which did not contribute an OpenSearch declaration, and his European Soccer gadget, which did, but did not return any results.

The container checks for OpenSearch contributions when a new gadget is loaded, and adds it's contribution to the search menu. The contribution contains a template URL that returns results, and information about the format the results are returned in. The container can query each url for results, and then aggregate the results in one UI.

2) Jane DaUser's page contains several gadgets that only contain OpenSearch contributions, and no UI. They are preloaded by the common container, and contribute to the search menu, without a visible presence on the page. Jane can search the gadgets content when she finds it necessary, but is not otherwise distracted by the gadgets themselves.

Many other scenarios are envisioned, but the key concept is to leverage existing OpenSearch Standard in investigating how search is relevant to gadgets in an Open Social container.

Links OpenSearch.org

Security Considerations

The XML and JSON search results will be fetched by using the existing container proxy service, to comply with browser security models.

Design thoughts

When using the feature OpenSearch, the gadget definition would include an OpenSearch declaration. The following basic OpenSearch parameters should be contained in all OpenSearch gadget contributions.

A complete gadget declaration would look something like this:

<ModulePrefs>

<Optional feature="opensearch">

<Param name="opensearch-description">

<OpenSearchDescription xmlns="http://a9.com/-/spec/opensearch/1.1/">
<ShortName>Example Search</ShortName>
<Description>Realtime Example Search</Description>

<Url type="*application/atom+xml*" method="get" template="http://search.example.com/search.atom?q=\{searchTerms\}"/>
<Image width="16" height="16">[http://search.example.com/favicon.png|http://search.twitter.com/favicon.png]</Image>
<InputEncoding>UTF-8</InputEncoding>
<SearchForm>[http://search.example.com/|http://search.twitter.com/]</SearchForm>
</OpenSearchDescription>

</Param>
</Optional>
</ModulePrefs>

The above is recommended for gadgets that are being hosted on a server that is different from the container rendering them. For a container that also hosts gadgets, the opensearch description can also be specified by providing a url to the full description, as seen below.

<ModulePrefs>
  <Optional feature="opensearch">
    <Param name="opensearch-url">http://www.example.com/search/files/examplesearch.xml</Param>
  </Optional>
</ModulePrefs>

Sample OpenSearch descriptions (for the full specification, see OpenSearch.org

RSS results returned as an RSS feed, can be aggregated using simple Dojo Datastore widgets, or a more elaborate custom UI

<OpenSearchDescription xmlns="http://a9.com/-/spec/opensearch/1.1/">
<ShortName>Web Search</ShortName>
<Description>Use Example.com to search the Web.</Description>
<Tags>example web</Tags>
<Contact>admin@example.com</Contact>
<Url type="application/rss+xml"
template="http://example.com/?q=\{searchTerms\}&pw=\{startPage?\}&format=rss"/>
</OpenSearchDescription>

JSON results returned as JSON, can be aggregated in a variety of ways, or served up to a third party for further processing.

<OpenSearchDescription xmlns="http://a9.com/-/spec/opensearch/1.1/">
<ShortName>Web Search</ShortName>
<Description>Use Example.com to search the Web.</Description>
<Tags>example web</Tags>
<Contact>admin@example.com</Contact>
<Url type=""application/json"
template="http://example.com/?q=\{searchTerms\}&pw=\{startPage?\}&format=rss"/>
</OpenSearchDescription>

HTML (container would just open results in an iframe, not a particularly useful scenario. Gadget adds itself as a searchable source, and a new web page is opened when the search is started.

<OpenSearchDescription xmlns="http://a9.com/-/spec/opensearch/1.1/">
<ShortName>Web Search</ShortName>
<Description>Use Example.com to search the Web.</Description>
<Tags>example web</Tags>
<Contact>admin@example.com</Contact>
<Url type="text/html"
template="http://example.com/?q=\{searchTerms\}&pw=\{startPage?\}&format=rss"/>&pw=\{startPage?\}&format=rss"/>
</OpenSearchDescription>

ContainerAPIs

osapi.container.Container.opensearch.getOpenSearchURLs

searchUrls osapi.container.Container.opensearch.getOpenSearchURLs(dataType)

Parameters

Returns

Retrieve all gadget search urls based on result data type. Containers may support zero or more of the data type.

osapi.container.Container.opensearch.getOpenSearchDescriptions

searchDescriptions osapi.container.Container.opensearch.getOpenSearchDescriptions(dataType)

Parameters

Returns

Retrieve all gadget search descriptions based on result data type. Containers may support zero or more of the data type. Retrieving the full descriptions allows containers to take advantage of more advanced opensearch functionality, such as paging.

osapi.container.Container.opensearch.addOpenSearchCallback

osapi.container.Container.opensearch.addOpenSearchCallback(callback)

Parameters

Registers a callback function to be called when the content OpenSearch registry change via adding or removing of gadgets.

osapi.container.Container.opensearch.removeOpenSearchCallback

osapi.container.Container.opensearch.removeOpenSearchCallback(callback)

Parameters

Removes the callback function previously registered with the opensearch feature.