chaos
LABORATORY

A brief introduction

This tutorial will attempt to explain in a simple manner how to create an OpenSearch plug-in for Firefox. These plug-ins appear in a drop-down menu in the Firefox Quick-Search bar (located right of the URL/Address bar) and help you perform quick searches across various search engines without having to visit the search page first. Pretty neat, eh?

These search plug-ins were in existence (for Firefox) for a long time. But only with the introduction of Firefox 2.0, the OpenSearch standards have been adopted.

OpenSearch is a collection of simple formats for the sharing of search results.

The OpenSearch description document format can be used to describe a search engine so that it can be used by search client applications.

The OpenSearch response elements can be used to extend existing syndication formats, such as RSS and Atom, with the extra metadata needed to return search results.

The example I’m going to demonstrate searches Invision Power Board (Bulletin Board System). You can make this plug-in perform searches on virtually any other Blogs / Bulletin Board / Content Management System / Search Engine with just some minor modifications in the way the search URL (along with keywords) is sent to the search engine. Here’s a screen-shot of two such plug-ins I’ve created for Astahost & Trap17 forums powered by IPB (Invision Power Board).

Advantages

There are quite a few advantages of shifting to the new OpenSearch format for these plug-ins, namely …

• OpenSearch plug-ins are universally supported across many browsers & search clients. Specially worth a mention here are Firefox and IE7 !!
• OpenSearch supports Autodiscovery of the plug-in, which means you don’t really have to instruct the user to click on a link on your site to install the plug-in. The search client can auto-discover the plug-in script based on a link provided between the HEAD tags of the page.If you wish to, the old-school click & install method can still be implemented.
• A lot of recent Blogs / CMS / BBS etc. softwares have started supporting the OpenSearch API, which provides a flexible common standard for XML based searches. A list of such software can be found here.

Without further ado, lets get down to business …

The actual plug-in

The OpenSearch plug-ins consist of a single XML file called the OpenSearch Description File. It follows a very simple syntax as shown below:

	engineName
	engineDescription
inputEncoding
	outputEncoding
	data:image/x-icon;base64, imageData
	


	
	searchFormURL

Most of the tags here need to be customised according to the Search Engine you’re going to use with the plug-in. Here’s what you need to modify here.

engineName

engineName enclosed within the ShortName tags specifies the name of the Search Engine as it’ll show up in the dropdown list. Replace this with the name of your Search Engine.

engineDescription

engineDescription enclosed within the Description tags shows up as a brief description of the Search Engine. Replace this with a suitable description.

inputEncoding

inputEncoding enclosed within the InputEncoding tags declares the encoding to use for search string / keywords you provide for a search. The search string is encoded in this format prior to sending to the Search Engine. Your best best is to use UTF-8 here to declare it as Unicoded text that’ll cover the whole Unicode Character Set.

outputEncoding

outputEncoding, enclosed within the OutputEncoding tags acts similar to InputEncoding and declares the character set to be used for producing the search results output. Even here the best used option is UTF-8.

Image

Enclosed within the Image tags, this specifies the image / icon to be used for the Search Engine. This icon turns up next to the search engine name in the dropdown list and also shows up to the left of the quick-search bar. The image is usually in a 16 x 16 pixels format.

The image data can be provided in two formats:

1. As a direct URL link to the location of the image file (gif/jpg/png etc.)
2. As base64 encoded data which can be embedded in the plug-in directly. This I believe, is a more elegant way of doing it. However, I couldn’t make it work properly for me. The image simply refused to turn up and hence I’d to resort to method 1.There’s a very good tool at URI Kitchen that encodes any uploaded image in base64 format. The encoded data can then be directly embedded in the plug-in.

Url

Enclosed within the Url tags, this provides the actual location of the Search Engine page. The method attribute defines whether to use GET or POST for fetching the data, while the template attribute points to the location of the search query page. NOTE, that IE7 doesn’t support the POST method and hence to make your plug-in compatible with both IE7 and Firefox, you should ideally use GET here.

Param

Further nested within the Url tags lie a series of Param tags which have two attributes - a name and a value. These act as parameters which are passed to the search engine while performing a query. This too, isn’t supported in IE7. However, you can use a dynamic variable called {searchTerms} to pass on keywords.

Say for instance, I’m searching Invision Power Board based forums. The standard search string in IP takes the format,

[html]http://www.domain.com/index.php?act=Search&CODE=show
&searchid=xxx&search_in=posts&result_type=topics&highlite=keywords
[/html]

If you study the URL carefully, you’ll notice that there are a couple of variables like act, CODE etc. which appear everytime along with same values. You can use Param tags to define key-value pairs for these variables, which will then be passed onto the Search Engine during a query.

The actual search keywords (as mentioned before) are available through a variable called {searchTerms}. IPB supports a variable called keywords in the search string and hence you can define a key-value pair like…

[xml]

[/xml]… to pass the keywords.Here’s a full working example of the plug-in I created for Astahost forums…[xml]
xmlns:moz=”http://www.mozilla.org/2006/browser/search/”>
AstaHost
AstaHost: Search the Forums
miCRoSCoPiC^eaRthLinG
microscopic.earthling@gmail.com
open
false
en-us
UTF-8

UTF-8
http://plugins.astahost.com/splugins/astahost.gif

http://www.astahost.com/index.php[/xml]

Here you’ll notice several other tags like Developer, Contact, SyndicationRight, AdultContent etc. which I haven’t discussed in this article. A detailed outline of all the OpenSearch tags can be found at: OpenSearch Description Elements.

Autodiscovery

If you recall I’d discussed a feature called Autodiscovery earlier on. This helps search clients automatically discover a plug-in embedded in your page. The process is quite simple. All you’ve to do is include a special LINK statement in the HEAD part of your page.

[html]

title=”xxx Search Plugin: By Author” href=”http://domain.com/plugin-file-name.xml”> [/html]

You simply need to modify the title and the href link to the actual plug-in file.When you visit a site with the plug-ins set to be auto-discovered, here’s how the drop-down menu in the quick-search box will look like…

Adding the plug-in Programmatically

You can also include the plug-in on your page in a click-and-install manner. The process has been simplified. All you need to do is provide a link to install the plug-in on your page and in the link, add the window.external.AddSearchProvider() JavaScript statement. Example is shown below.

[html]Link Text
[/html]

Clicking on this link will cause Firefox to pop-up a dialog box asking the visitor for a confirmation of plug-in installation. Example of the dialog box …

Working examples can be found at the Astahost Plug-ins Page.

Any questions / confusions ?? Feel free to leave a comment and I’ll make sure to get back to you.