Integrating Site Search Into Firefox and IE7

Filed: Sun, Jan 21 2007 under Programming|| Tags: search site xml javascript

Internet Explorer 7 and Firefox 1.5+ offer a built in search box and the good news is that it's super easy to incorporate your site's search into those boxes. You don't even need any server-side scripting to do this! You can do it with plain HTML and Javascript. You can even use google, yahoo, or any other service as your search engine for your site.

Step 1: The link

In your site's HTML, insert the following into the <head> area. Adjust the text appropriately for your site.

<link title="my site" type="application/opensearchdescription+xml" rel="search" href="http://www.mysite.com/search.xml">

Much like an embedded RSS link, this line lets the browser know where to get more information about including your site search in its search engine list.

Step 2: The XML

Create a new, blank text file on your site and name it search.xml (the filename in the url in step 1). Next, insert the following text into your new file.

<?xml version="1.0" encoding="UTF-8"?>
<OpenSearchDescription xmlns="http://a9.com/-/spec/opensearch/1.1/">
  <ShortName>MyPlace</ShortName>
  <Description>MyPlace is a happy, shinning place where bunnies dance and play.</Description>
  <Image height="16" width="16" type="image/vnd.microsoft.icon">http://www.mysite.com/favicon.ico</Image>
  <Url type="text/html" template="http://www.mysite.com/search.php?search={searchTerms}"/>
</OpenSearchDescription>

This is pretty straightforward stuff. It is, after-all XML -- its meant to be easy to read. The first line merely defines the XML version being used and the character set. The second line denotes our search engine information record and which template it's using (a9 in this case). ShortName is the short name of your site which appears in the drop down box of the search engine selector.

Shortname should match exactly, the title of your link. If there is a variation between the two then the user will be offered the chance to add your search engine twice. While that may seem cool, it's actually very confusing to your visitor.

Description isn't used so much, but Image tells the browser where it can snag your site's icon.

Finally you give the URL of your search engine and wherever you place {searchTerms} the browser will pass whatever the user typed in the input box, url encoded. You need to specify the full domain name to the search page. The user may not actually be on your site when he choses your search engine so the Url needs to contain the full location to your search page, not just the page name itself.

Step 3: The Search

You actually don't need a server side script to handle the search. It can be a simple web page with javascript to read the url, extract the search terms and then do a simple document.location.href to redirect the page to say google, yahoo, live, or some other service.

Here's an example which extracts the search terms from the url (anything after ?), adds a "site:mysite.com" modifier to the search terms so google will only search the documents on your site, and then redirects the browser to google. Create a new html file -- search.html for example -- and insert the following code in the <body>:

<script type="text/javascript">
var searchTerms = document.location.href.split(/\?(.+)$/);
var gooUrl = 'http://www.google.com/search?q=site%3Ahunlock.com+'+searchTerms[1];
document.writeln('<BR>'<BR>'<BR>'<BR>Redirecting to: <a href="'+gooUrl+'">'+gooUrl+'<\/a>');
document.location.href=gooUrl;
</script>

The first line extracts everything on the url line after the question mark so your XML, Url tag will need to have a template similar to this...

  <Url type="text/html" template="http://www.mysite.com/search.html?{searchTerms}"/>

The second line seeds the google url. You'll need to change site%3Ahunlock.com to site%3Ayoursite.com whatever yoursite.com happens to be. the %3A is a url encoded colon so in plain english this would be site:someurl.com.

The writeln is a safety measure in case for some reason the page doesn't redirect -- it will give the user something to click.

document.location.href simply redirects the page to the URL we built in gooUrl.

Bringing it all together

If you followed step #1, one of your pages should have the following link in the <head> section of the HTML.

<link title="my site" type="application/opensearchdescription+xml" rel="search" href="http://www.mysite.com/search.xml">

... adjusted to your site's URLs of course. When you visit the page with that link in it you should now see an option to add your site's search engine and when you type in your search terms you should be redirected to Google which will show only pages on your site with those search terms. And of course, if you prefer, you can modify the javascript to call yahoo or live or any other engine based on your preferences.

A More Direct Method

You might have noticed that the javascript search is actually unnecessary. You can have the search engine line directly in the XML file itself. This is absolutely correct, you can indeed bypass the need for the javascript redirect simply by setting up your xml file as such...

<?xml version="1.0" encoding="UTF-8"?>
<OpenSearchDescription xmlns="http://a9.com/-/spec/opensearch/1.1/">
  <ShortName>MyPlace</ShortName>
  <Description>MyPlace is a happy, shinning place where bunnies dance and play.</Description>
  <Image height="16" width="16" type="image/vnd.microsoft.icon">http://www.mysite.com/favicon.ico</Image>
  <Url type="text/html" template="http://www.google.com/search?q=site%3Ahunlock.com+{searchTerms}"/>
</OpenSearchDescription>

The Catch

There's a very good reason NOT to do this however. Once the user ads your search engine the XML file seems to be cached forever. Shift reload, cntrl+shift reload, nothing seems to get that XML re-checked. The user will have to manually remove your search engine and then re-add it for any changes in the XML file to take effect.

So you always want the XML file pointing to one of your pages. That way if you ever want to change how your site search works (switching from Google, to yahoo or to your own in-house search engine) you can make a change to your javascript redirect and rest easy knowing all your existing visitors will get the change immediately.

Adding a search engine via a link.

If your visitor is using firefox you can add a link offering to add the search engine instead of just hoping they notice it available to add in the search engine list. This is done with a simple function (From the Mozilla Documentation)...

function addEngine()
{
  if ((typeof window.sidebar == "object") && (typeof window.sidebar.addSearchEngine == "function"))
  {
      window.sidebar.addSearchEngine(
          "http://www.mozilla.org/projects/search/mozilla.src",  /* engine URL */
          "http://www.mozilla.org/projects/search/mozilla.gif",  /* icon URL */
          "mozilla.org",                                         /* engine name */
          "Web" );                                               /* category name */
  }
}

When adding a search engine in this manner there are some special rules.

  • search engine filename extensions must be ".src"
  • search icon filename extensions must be one of the following: ".gif", ".jpg", ".jpeg", or ".png"
  • when using the window.sidebar.addSearchEngine() function, the basename of the engine URL and the icon URL (in this example, "mozilla.src" and "mozilla.gif") must exactly match, except for the filename extension
  • the "engine name" parameter is only used for display in the confirmation dialog (which the user must agree to)
  • if the "category name" doesn't exist, it will be ignored (Note: this behavior may change so that the category is instead created)

The catch is that your src file is a sidebar definition file. It's not an opensearch xml file. It's different. Here's the template you'll need to add and modify.

<search
 version="1.0"
 name="Your search engine name"
 description="The best search engine ever made" 
 action="Your search URL"
 searchForm="A search form if you have it"
 method="GET">

<input name="all" user>
<input name="src" value="moz">

</search>

<browser
 update="Url of this search file"
 updateIcon="Url to the icon"
 updateCheckDays="# indicating how often to check this file for changes">

Direct Links with IE (short and sweet)

Internet explorer takes a differnt route and infinitely simpler route.

window.external.AddSearchProvider(sUrl)

Here sUrl is a string pointing to your open search xml file.

Adding a search engine with a link -- cross-browser edition

Here's a cross-browser add engine routine. You'll need to tweak it with your search settings of course but it should handle firefox and IE quite nicely.

function addEngine()
{
  if ((typeof window.sidebar == "object") && (typeof window.sidebar.addSearchEngine == "function"))
  {
      window.sidebar.addSearchEngine(
          "http://www.mozilla.org/projects/search/mozilla.src",  /* engine URL */
          "http://www.mozilla.org/projects/search/mozilla.gif",  /* icon URL */
          "mozilla.org",                                         /* engine name */
          "Web" );                                               /* category name */
  } else {
     if (window.external.AddSearchProvider) {
        window.external.AddSearchProvider('http://url.to.your.xml.file');
     }
  }
}