Global Moxie

http://globalmoxie.com/blog/opensearch-browser-search-field.shtml

OpenSearch: Add Your Site to Browsers’ Built-in Search

Let visitors search your site directly from their browser’s search field.

Faithful reader, I have no doubt that there are moments—daily, perhaps—when you think, “Hey, I sure wish I could lay my hands on that witty/insightful/subtle comment that Josh made about topic X.” ....Or, y’know, maybe not.

In the unlikely event that this urge should one day descend upon you, I want to make it easy for you to scratch that itch as quickly as possible. If you’re reading this in Firefox 2 or Internet Explorer 7, you can now search this site right from your browser’s built-in search box.

This little bit of magic is achieved through an elegant little format called OpenSearch, mixed with Big Medium’s built-in site search. If you’re so inclined, you can do it for your own site, too. Herewith, a tutorial.

Collect your search details

The central element that makes this fandango tick is a XML text file that you place on your server. This file gives browsers three important pieces of information:

Name of your search.
This is how your site’s search will appear in the browser’s search field, so it should be short and sweet, typically the name of your site. I use: “Global Moxie”
Search description.
A brief description of your search and what it does. I use: “Search Global Moxie for info about Big Medium.”
Search URL.
The URL location of your search engine, with the placeholder {searchTerms} representing the text to search.

Assemble your search URL

Sorting out the search URL for a Big Medium-powered site takes a little bit of rummaging, but it’s not difficult. First identify the base URL location: It’s the bm-search.cgi file in your installation’s moxiebin directory. For example:

http://example.com/cgi-bin/moxiebin/bm-search.cgi

A second element tells Big Medium what site you’re searching. This gets added, along with a question mark, to the URL like so ?bms=1:

http://example.com/cgi-bin/moxiebin/bm-search.cgi?bms=1

To find out what number to use for your site, go to a page that displays the Big Medium search form (generated with the <%search%> widget), and do a quick search. In the URL of the results page, you’ll see the bms= value. That’s the number to use.

The last element is the search query itself, and it’s handled like so, separated from the rest of the URL with a semi-colon: ;bmq={searchTerms}

Putting it all together, we get:

http://example.com/cgi-bin/moxiebin/bm-search.cgi?bms=1;bmq={searchTerms}

Create an OpenSearch XML file

With that info in hand, you’re ready to build your OpenSearch XML file. Here’s the format:

Adding a new search engine in IE7. Click to enlarge.

<?xml version="1.0" encoding="UTF-8"?>
<OpenSearchDescription xmlns="http://a9.com/-/spec/opensearch/1.1/">

    <ShortName>SEARCH-NAME</ShortName>
    <Description>SEARCH-DESCRIPTION</Description>
    <Url template="SEARCH-URL"

         type="text/html" method="GET" />
    <Image height="16" width="16" type="image/vnd.microsoft.icon">http://beta.bigmedium.com/favicon.ico</Image>
    <OutputEncoding>UTF-8</OutputEncoding>
    <InputEncoding>UTF-8</InputEncoding>
</OpenSearchDescription>

You can just copy this verbatim and replace SEARCH-NAME, SEARCH-DESCRIPTION and SEARCH-URL with the name, description and URL described in the previous section. Be careful: This is a XML file, so if your name, description or URL includes certain symbols, you need to replace them with the appropriate XML entities. Specifically: & ampersands (&), quotation marks ("), apostrophes ('), < symbols (<) and > symbols (>)

Once you’ve built your XML file, upload it to your server at a location like this:

http://example.com/opensearch.xml

Let browsers know about your OpenSearch file

Both Firefox 2 and Internet Explorer 7 support “auto-discovery” of your custom search engine. When the browser detects your OpenSearch file, the browser’s search field highlights ever-so-subtly to indicate that there’s a new search engine available. Clicking the search field’s pulldown menu offers the option to add the search.

To trigger this behavior, you have to tip off the browser with a <link> tag in your page. In Big Medium, you add this link by going to “Settings>HTML Preferences” and then to the “Document and Page Header” screen. Add the following <link> tag to the “Additional HTML to include in header” field, replacing the title attribute with the short name you used in your OpenSearch file and the href attribute with the URL location of your OpenSearch file:

<link title="Example.com" href="http://example.com/opensearch.xml"
 type="application/opensearchdescription+xml" rel="search">

After rebuilding your pages, you’ll see that the search field in Firefox and Internet Explorer now offer the option to search your site. Hey, not too bad, but you have to admit... it’s still a little bit understated.

Be more direct

You can use a link to be bolder about proposing your site’s search engine to visitors. The following HTML snippet displays a link to supporting browsers (for now, Firefox 2 and IE7) allowing visitors to add your search to the browser. Add this to your Big Medium template(s) where you would like the link to appear:

<a href="#" id="addSearch" style="display:none">
    Add example.com search to your browser
</a>

<!-- edit the url below -->
<script type="text/javascript" language="javascript">
(function(){

    //edit this to point at your opensearch.xml file
    var url = "http://www.example.com/opensearch.xml";

    var add = function(ev){
        window.external.AddSearchProvider(url);
        Event.stop(ev);
    };
    if (  typeof window.external == "object"
       && typeof window.external.AddSearchProvider != "undefined" ) {
        var a = $('addSearch');
        Event.observe(a, 'click', add);
        a.toggle();
        a=null;
    }
})();
</script>

To customize that for your own site, just edit the “Add example.com” link text and edit this line to use the actual location of your OpenSearch file:

//edit this to point at your opensearch.xml file
var url = "http://www.example.com/opensearch.xml";

The JavaScript listed above uses the Prototype.js library which is included in all Big Medium pages. If you want to use this code snippet outside of Big Medium, be sure to include the Prototype library in your page.

Learn more

Check out these links to get the inside skinny on OpenSearch and its applications:

OpenSearch.org
Creating OpenSearch Plugins for Firefox (Mozilla Developer Center)
IE7 OpenSearch Tutorial (IE blog)

Tags: bigmedium, javascript, opensearch, search, webdev