Create a custom search engine for Firefox, IE, Chrome

By Eoin on 26 January 2010.

Custom search engines in your browser are all the rage these days. Well, more honestly, they’re not. They won’t make girls swarm in your direction, but they people search your site directly from within in their browser (instead of visiting your site first).

I’ll give you step-by-step directions on how to create your own browser search engine. I put together one for searching the dictionary at Irishionary.com, and you can see it as an addon on Mozilla.org.

In Firefox, my custom search engine look like so:

Custom browser search engine

Custom browser search engine for Irishionary.com.

Creating a browser search engine is quite simple. You write an XML file to describe your search functionality, then you expose that XML file to your site’s visitors. The XML file specification is called OpenSearch, a standard to describe search engines that your browser will understand. We’ll have the search results display as a web page, but you can have the spat back as JSON or whatever.

What you’ll need

  1. A knife.
  2. A rubber band.
  3. A web site with its own search functionality that accepts GET requests (for compatibility with Internet Explorer). For example, you’ll need a page such as http://www.example.com/search.php?query=beer.

Step 1: Create your XML description file

Copy-paste this XML code to a file such as search.xml. You can see mine live in action at .

<?xml version="1.0" encoding="UTF-8"?>
<OpenSearchDescription xmlns="http://a9.com/-/spec/opensearch/1.1/" xmlns:moz="http://www.mozilla.org/2006/browser/search/"> <ShortName>Irishionary.com</ShortName> <Description>Irish language dictionary.</Description> <Tags>gaeilge irish gaelic dictionary</Tags> <Contact>info@irishionary.com</Contact> <InputEncoding>iso-8859-1</InputEncoding> <OutputEncoding>iso-8859-1</OutputEncoding> <Image width="16" height="16" type="image/x-icon">http://www.irishionary.com/favicon.ico</Image> <Image width="64" height="64" type="image/png">http://www.irishionary.com/resources/images/search_logo.png</Image> <Url type="text/html" method="get" template="http://www.irishionary.com/process/search.php?search_phrase={searchTerms}"> </Url> <Url type="application/opensearchdescription+xml" rel="self" template="http://www.irishionary.com/scripts/search.xml" /> <Query role="example" searchTerms="beer" /> <Language>en-us</Language> <Language>en-gb</Language> <Language>ga</Language> <moz:SearchForm>http://www.irishionary.com/</moz:SearchForm> <AdultContent>false</AdultContent> <Attribution>Search data copyright eTeanga (www.eteanga.ie)</Attribution>
</OpenSearchDescription>

Step 2: Customise your XML file (boring)

So the code above describes the Irishionary.com Irish Dictionary search engine. Use your common sense when editing the tags.

Here are some boring details on some of the parts that may need an explanation. There is a full specification of the OpenSearch format available.

  • <InputEncoding> and <OutputEncoding> describe the character encoding that your search engine first accepts, and then spits out (in our case, the character encoding of your HTML search results).
  • The <Image> tags describe two sizes of icons that represent your service. The browser might use the smaller icon to display beside the search box. The bigger image may be used by a directory of search engines, for example.
  • The first <Url> tag is the meat of this whole operation. It describes where to send the search query to get the results. It’s the http://www.example.com/search.php?query=beer URL I mentioned above. In the XML tag, note that {searchTerms} is how you capture what the person typed into the search box. Using our original example, you’d put in http://www.example.com/search.php?query={searchTerms}
  • The second <Url> tag is the URL for where you’re going to publish your XML file online. This will allow the browser to check for updates to your XML in the future.
  • The <Query> is a way to give an example search query. I don’t know where this is displayed.
  • The <Language> tags specify which languages your search engine will accept. It may only be one language. I think you can also use * as a wildcard for “any language”.
  • We’re almost there! <moz:SearchForm> is a Firefox-specific tag which points to where the search form is online.

Step 3: Upload your XML file

Do it. I haven’t been able to get Firefox to recognise a file hosted locally on my machine.

Step 4: Tell your browser about your search engine

There are a couple of ways to test your engine. The first is to let your browser “discover” it. In the HTML of a test page on your site, add the following code inside the ** tags. Customise it to point to where your XML is found.

Now visit that HTML page in your browser to “auto-discover” the tag you’ve included.

Add to Firefox

When viewing the HTML page that includes the <link> tag above, click the little highlighted arrow beside your default search engine in the search bar. It should look something like the following:

Highlighted browser search box

The little arrow gets highlighted when Firefox detects your search engine mentioned in the tag.

When you click the arrow, you’ll see the list of installed search engine with the option to “Add” your own engine. If your engine hasn’t been listed, there’s something wrong with your <link> tag above. Once added, you can test your engine!

Add to Chrome

Google give instructions on how to add a detected engine to the browser.

Step 5: Test your search engine

In Firefox, select your engine from the list of search engines, and perform a search. Check out if it brings you to your site’s search results page. If you’ve gotten this far, get someone to pat you on the back. In fact, this may be one of your life’s biggest achievements. Well done.

You’ll want to promote the search engine on your site to your visitors. It needs a little Javascript link to get this done:

<a
href="javascript:window.external.AddSearchProvider('http://www.irishionary.com/scripts/browser_search.xml');">Add
engine</a>

Customise the URL in there to point to your own XML file. Now visitors can install the search engine directly from your site.

(Yet Another) Bonus step: Submit to Mozilla

A good way to promote your search engine is to submit it to Mozilla’s addons repository for Firefox. It takes some effort. You’ll need to create a developer profile, then submit your addon for testing. Once you move it out of the “sandbox” it will be available publicly and marked as “experimental”. Have your users test it out for a while, then you can ask for it to be fully released. Get started on Mozilla’s developers’ guide.

Congrats, you’re created a browser search engine. I hope you’ve learned some bits here. There is a good best practices guideover at OpenSearch’s site.

About and Contact · All posts

Share Your Opinion!