Firefox / Internet · January 7, 2007 16

Tutorial: Creating OpenSearch Plugins for Firefox (adds to the QuickSearch bar)

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).

OpenSearch Plug-ins Dropdown List


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:

<?xml version="1.0" encoding="UTF-8"?>
<OpenSearchDescription xmlns="">
    <ShortName>Chaos Laboratory</ShortName>
    <LongName>Chaos Laboratory: Blog Search</LongName>
    <Description>Search through articles posted on the Chaos Laboratory Blog</Description>
    <Developer>Name of developer</Developer>
    <Contact>Email of developer</Contact>
    <Description>Description of plugin</Description>
    <Tags>Tags / keywords separated by spaces</Tags>
    <Attribution>Copyright / Attribution</Attribution>
    <Query role="example" searchTerms="Apple"/>
    <Image height="16" width="16" type="image/">https://url-to-favicon.ico</Image>
    <Image height="64" width="64" type="image/png">https://url-to-favicon.png</Image>
    <Url type="text/html" template="https://url-including-search-query"/>

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.

ShortName: 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.

Description: Shows up as a brief description of the Search Engine. Replace this with a suitable description.

InputEncoding: 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: 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: 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. Multiple image tags are permitted to accommodate icons of different sizes and formats.

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: 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.

Url Parameter: 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 IPB takes the format,

If you study the URL carefully, you’ll notice that there are a couple of variables like act, CODE etc. which appear every time 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}.

Here’s a full working example of the plug-in I created for Astahost forums…

<?xml version="1.0" encoding="UTF-8"?>
<OpenSearchDescription xmlns="">
    <LongName>AstaHost: Search the Forums</LongName>
    <Description>Search through posts on the AstaHost Forums</Description>
    <Description>Search for web-related topics like Hosting, Apache, PHP, MySQL, CSS, XHTML, JavaScript, jQuery, Angular and much more!</Description>
    <Tags>hosting apache php mysql css xhtml xml javasript jquery angular salesforce programming</Tags>
    <Attribution>Search data from AstaHost,</Attribution>
    <Query role="example" searchTerms="Apple"/>
    <Image height="16" width="16" type="image/"></Image>
    <Image height="64" width="64" type="image/png"></Image>
    <Url type="text/html" template="{searchTerms}&search_in=posts&result_type=topics&highlite=keywords"/>

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.


If you recall I’d discussed a feature called Auto-discovery 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.

<link rel="search" type="application/opensearchdescription+xml" href="/opensearch.xml" title="AstaHost Search Plugin" />

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…

OpenSearch Plug-in Autodiscovery Screenshot

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.

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 …

OpenSearch Plug-in Click & Install Screenshot

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.