Monday, December 26, 2011

Creating a search plugin for Firefox

You have probably used multiple search engines with Firefox's OpenSearch plugins. Many websites currently advertise their own search engines using the Autodiscovery method supported by Firefox. You can either add their search engines or you can find some custom ones on Add-ons for Mozilla.

However, sometimes you just need something different, something that fits your specific needs and can't be found anywhere else. In those cases, the best is to do it yourself.


Some browsers, like Chromium, provide an easy way for manually creating search plugins right in the user interface, but with a clean installation of Firefox it isn't that simple.
So, how to create a simple Firefox search plugin without wasting much time investigating? I'm gonna give you a hand for that:

You will need to create a little XML file for each search engine you want to add.

Let's take a look at an example that uses Google Translate:

<SearchPlugin
    xmlns="http://www.mozilla.org/2006/browser/search/"
    xmlns:os="http://a9.com/-/spec/opensearch/1.1/">
<ShortName>Translate</ShortName>
<Description>Google Translate</Description>
<InputEncoding>UTF-8</InputEncoding>
<Image width="16" height="16">http://translate.google.com/favicon.ico</Image>
<Url type="text/html" method="GET" template="http://translate.google.com/#en|pt|{searchTerms}">
</Url>
</SearchPlugin>

Here I am using Google Translate to always translate whatever text I put in the search box from english to portuguese. You can use it as a model for your own search plugins, it will fit most of the situations, as long as they use the GET method.

Me searching for the translation of "flotsam"


Now a look at each section:

<SearchPlugin
    xmlns="http://www.mozilla.org/2006/browser/search/"
    xmlns:os="http://a9.com/-/spec/opensearch/1.1/">
Here we define the namespaces for this XMLfile. Just put it always like this and it will work unless the format changes in the future.

<ShortName>Translate</ShortName>
<Description>Google Translate</Description>
<InputEncoding>UTF-8</InputEncoding>
Give a name to your search engine, inside the ShortName tag, a description inside Description and what encoding to use when entering the text to be searched inside InputEncoding. I recommend UTF-8 unless you are into some heavy characters stuff.

<Image width="16" height="16">http://translate.google.com/favicon.ico</Image>
This defines the icon to use with your search engine. Find the URL of the favicon and put it inside the Image tag and Firefox will automatically download the icon.

<Url type="text/html" method="GET" template="http://translate.google.com/#en|pt|{searchTerms}">
</Url>
</SearchPlugin>
This is the most important part of the file because it tells what the link is and where to put the your search terms. In the case of Google Translate there are the source language, destination language and search terms, all separated by a pipe (|). I have fixed the languages from "en" to "pt" and where the search terms should be I entered {searchTerms}, which will be parsed by Firefox and replaced by what I enter in Firefox's search box.

In order to create an Url tag for other search engine website, you should first make a few tries to see where the link changes (where your search terms are being written). When you find it, just replace the random search terms with {searchTerms}, copy the link and put it inside Url tag template attribute.

Well, we have created the XMLfile. Now we need to know where to put it:

On Windows, assuming it is installed on the C: drive, you should move the XML file to:
C:\Users\yourUsername\AppData\Roaming\Mozilla\Firefox\Profiles\<yourProfileID>.default\searchplugins C:\Document and Settings\yourUsername\Application Data\Mozilla\Firefox\Profiles\<yourProfileID>.default\searchplugins (Windows XP/2000/2003)

On Linux, the same can be achieved by moving it to:
~/.mozilla/firefox/<yourProfileID>.default/searchplugins

On Mac OS, you can move it to one of these folders:
~/Library/Mozilla/Firefox/Profiles/<yourProfileID>.default\searchplugins
~/Library/Application Support/Firefox/Profiles/<yourProfileID>.default\searchplugins

If the directory searchplugins directory does not exist, feel free to create it.

Attention: If you later change the search plugin file and there are no changes in Firefox (even after restarting it), try to move the file away from the searchplugins directory and close Firefox (thus forcing it to sync everything). Then, before opening it again, move the file back to the searchplugins directory. I have witnessed this behaviour with Firefox 9.0.1 on Windows 7, but not on Arch Linux.

Be aware that the XMLfile I described in here isn't the actual OpenSearch format but rather a Firefox variant for locally stored OpenSearch plugins. However, mostly everything is the same and you can find more information at MDN.
Also, Firefox may change your XML file once it gets loaded and alter things like the favicon URL (replacing it with base64 encoded data, for caching).

OpenSearch is supported in Firefox 2.0 and all versions above.


This plugin is also available for direct download: Here.