June 25, 2009

Perforce KB OpenSearch plugin

Product Branding

Related to microformats, OpenSearch is a "collection of simple formats for the sharing of search results". Or in terms most people are likely to be familiar with, it's part of what allows you to do web searches through your browser's search bar.

I thought that being able to search our knowledge base in that way might be useful for some folk, so I whipped up a quick example of how to do it. OpenSearch is just an XML namespace, so creating a definition for any search provider is just filling in the blanks of an XML file. Note that it requires either Firefox 2.0+ or IE7+. And from a superficial search, it seems that the Opera browser has its own method for adding custom searches, so this example probably won't work as-is.

Here is the XML file for our KB. To load it into your browser, just follow the link to this sample file and then click on the drop-down menu next to your search bar so you see a window like this:

Once you click the 'Add' option, you can select it from the list when you want to search the KB for something. Or, if it displeases you, remove it via 'Manage search engines...' (probably a Firefox-specific option).

Making one for either your own site or someone else's isn't that hard. Seesome of the references out there.

One little trick is to embed your favicon into the XML definition using the data url scheme, which lets you avoid needing a separate file for it. You don't need to understand the RFC in order to use it - there are tools out there that will export data in base64.

The OpenSearch format (or at least how the browsers deal with it) can be a bit tricky. Pretty much everything needs to be right, or it won't get imported into the list of available search providers. I've found that one thing you should check first for errors is the embedded search URL. Since it's inside of an XML file, you need to properly escape its data or it won't be valid. This means "&" becomes "&" and so forth.

If things are silently failing, e.g. you load your HTML file linking to the XML search definition and you don't get your provider in the drop-down menu, another thing you can do to get more feedback on what's going on when debugging is to make use of a web server to see what the browser is fetching. It's a good way of catching typos, missing files, etc. If the browser doesn't even ask for your files, then maybe there's something wrong with the XML file.

If you've already got a running web server, then go ahead and use that, but if not and if you want a light-weight way of starting one without having to do any configuration, then I recommend running the following little Python script in the same directory that you've got your files. It starts a basic web server on port 8000 and prints its log to the console. What could be easier?

python -c "import SimpleHTTPServer;SimpleHTTPServer.test()"

And there you have it - OpenSearch can do a lot more than what I've shown here, but as far as a quick convenience to access or documentation goes, simple is good.