Search Engines

The XML File

We'll start by making the XML search file, which actually is most important file of our search add-on.
Here's an example, taken from a search add-on called Songza Search

<?xml version="1.0" encoding="UTF-8"?>
<OpenSearchDescription xmlns="http://a9.com/-/spec/opensearch/1.1/">
    <ShortName>Songza Music Search</ShortName>
    <Description>Search for Music with the Songza search engine</Description>
    <Image height="16" width="16" type="image/x-icon">http://songza.com/favicon.ico</Image>
    <Url type="text/html" template="http://www.songza.com?q={searchTerms}"/>
</OpenSearchDescription>

So what's happening here?
First of all we'll start by making the XML declaration. This is mandatory
Then we make the root element called OpenSearchDescription. We also declare the OpenSearch XML Namespace which we're going to use.
Inside the root element we declare all the information the Search Plugin is going to need.

The <ShortName> tag is the name of your search plugin, this is displayed as default in your searchbar.
The <Description> tag, which describes your Search Plugin, right now the description isn't displayed in Songbird, but it's good practice to describe you Search Plugin anyway.
The <Image> tag is the image displayed left to the searchbar. the attributes should just be left as they are. Height and width just sets the height and width of the displayed image, but Songbird makes you image 16 * 16 anyway. The value of this tag is the path to the icon. This could be an http:// url or a chrome:// url.

And finally the <Url> tag. This is where you describe the searchtemplate your search engine use. In Songza the search query should be assigned to a GET variable called q.
The {searchTerms} are replaced by the search string the user enter.

The Script File

But just because you got an XML file in the contents of your add-on doesn't make Songbird find it. We'll have to append our search plugin to the search engine list.

I'll comment in the code:

// We create an object for our plugin, you could make a single function, but I prefer to make an object. 


var SongzaSearch = {
   
    init: function() // This function will be called on startup
    {
        var searchService = Components.classes["@mozilla.org/browser/search-service;1"] // We create an object of the XPCOM interface SearchService
                            .getService(Components.interfaces.nsIBrowserSearchService);
        
        searchService.addEngine( // We add our searchengine to the list
        "chrome://songza-search/content/songza.xml", // The URL of our XML file
        Components.interfaces.nsISearchEngine.DATA_XML, // It's a XML file
        "chrome://songza-search/skin/songza.ico", false); // The path to our icon
    }
}

window.addEventListener("load", SongzaSearch.init, false); // This will cause SongzaSearch.init to be called when Songbird loads

 

The Overlay

So now we only need the overlay, to make our code execute, everytime the user starts up Songbird. In our chrome.manifest well just add this line:

overlay chrome://songbird/content/xul/layoutWithBrowserOverlay.xul chrome://songza-search/content/overlay.xul

This will cause our overlay.xul (explained in a minut) to be overlayed on Songbird with browser, which means that it wont be overlayed to mini-player.

Now for overlay.xul

<?xml version="1.0" encoding="UTF-8"?>
<overlay id="songza-search-overlay" xmlns="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul">

  <script type="application/x-javascript" src="chrome://songza-search/content/search.js"/>
</overlay>

We just make Songbird load out JavaScript everytime it starts up. Actually the type attribute isn't necessary to make it work, but, again, it's good practice.


That's it for now! I've attached a .zip file with all the files in Songza Search. so you can download it, and use it as a template for your own Search add-ons

No go make Search Plugins for all your favorite search engines!