how to: create firefox search plugins

Last week I had some time so I figured I’d create a search plugin for Firefox to search the Orlando Wiki. I thought this would be a quick effort. Alas, I was wrong. Sure, the Mycroft docs are good, but I figured there had to be something on the web with a quick howto. Since I didn’t find one, here it is.

Step One: Create a .src File

The
.src file is what tells the search feature how to conduct the search
and, optionally, how to interpret the results. Here’s the .src file I
created: 

<search	
version="7.1"
name="Orlando Wiki Search"
description="Search the Orlando Wiki"
action="http://orlando.citywikis.com/tiki-searchresults.php"
method="GET"
target="_blank"
>

<input name="sourceid" value="Mozilla-search">
<input name="words" user="">
<input name="where" value="pages">

This
is all that’s needed for a very basic search that uses GET (a
querystring URL) to perform the search and displays the results page in
the browser. Let’s take a look at this file and what it means.

The version=”7.1” attribute of the search tag should be just
that. 
Don’t mess with it. The name attribute is what you can use to give your
plugin a name. The description attribute is for the description. The
action attribute is the base URL to your search page. This must be a
page that uses GET (a querystring). This is everything before the ? in
a URL that you would see in your browser’s address bar when you do a
search. The method attribute should be GET. Use target=”_blank” to have
your results open in a new window (or tab, depending on your config).
Use target=”” to open in an existing page/tab.

The next few input
tags are used to build the querystring sent to the server. The sourceid
input should be there and left as it is above—don’t ask me why, I just
recall that it is part of the spec. The next two input tags need to
correspond to the GET variables your server is expecting to execute the
search. For example, when I go to the wiki and do a search for wifi,
the URL that is used is: http://orlando.citywikis.com/tiki-searchresults.php?search=go&words=wifi&where=pages

The search=go is the value of the search button on the search page and
isn’t used to process the search—you can tell by leaving it our of the
URL. The words=wifi is where the search string I typed is passed in. To
make this into an input tag, take the field name (words) and use that
as the name attribute value. The search terms entered in a Firefox
toolbar search will be passed in as the user value (or at least that’s
what I’m assuming since I have no idea about the internals and I’m too
lazy to read the docs ;-). That is where the user=”” comes from in the
input tag.

The last input tag is used to specify where to
search.  This is determined by the wiki—I’m just using the
name=”where” and value=”pages” to match the querystring.

OK, now
you have your .src file. Save it. I used orl-wiki-search.src as the
filename. Note that you will be using the base name (without the
.src extension) of this file later on and it will also show up
in the user’s searchplugins folder when it is
installed, so pick something that makes sense.

Step Two: Creating the Icon

When
you load a search plugin, it has an icon that it shows in the toolbar.
From what I gather of the spec, this is optional but having no icon is
just lame, so let’s create one. Use your favorite image editing program
to create a 16×16 PNG file. You can use GIF also, but I couldn’t get it
to work and don’t really care why since PNG worked fine ;-). Save that
file with a .png extension using the same base name as your .src file.
This is important if you want it to work. Since my .src file is
orl-wiki-search.src, my icon file is orl-wiki-search.png.

Step Three: Adding JavaScript and Creating the Install Link

To install a search plugin, you have to use a bit of JavaScript code which you’ll call using a link. Here’s the code:

<script type="text/javascript">
function addEngine(name,ext,cat)
{
if ((typeof window.sidebar == "object")
&& (typeof window.sidebar.addSearchEngine == "function"))
{
window.sidebar.addSearchEngine("http://chris.geekcollective.com/" + name + ".src",
"http://chris.geekcollective.com/" + name + "." + ext,
name, cat );
}
else
{
//you could put an error handler here
;
}
}
</script>

Put
this in the HEAD of your page or an external .js file that is linked in
to your page. You can put it in the BODY in a pinch (as I did since I
put this on my blog and doing per-page HEAD modifications wasn’t
something I wanted to think about. I was lazy and didn’t feel like
changing the script I lifted to figure out the base URL of the site it
is on so you’ll need to change http://chris.geekcollective.com/ to your own site if you use this. Other than that, this doesn’t need to be modified.

To create the link that will be used to install, use the following HTML code:

<a href="javascript:addEngine('orl-wiki-search', 'png', 'Orlando Wiki Search')">install it</a>

Change
orl-wiki-search to the base name of your .src and .png files. Leave png
as it is unless you are using a gif file, then change it to gif. I’m
sure the third parameter for the category should be something different
but since I couldn’t find any good docs on it, I made up my own. It
seems to work, but if anyone has any info. on this, I’d like to know.

That’s it. See it work here.

 

2 thoughts on “how to: create firefox search plugins

Leave a Reply

Please log in using one of these methods to post your comment:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s