How to write a rough and ready Mozilla/Firefox Search Plugin

After writing my first search plugin, I can reassure you it’s dirt simple – at least at the basic level. There are a lot of options, and they – and their respective importance – can be a little vague. The place to start is the Mycroft documentation – especially the Quick Start Guide.This post was also useful (to help you from getting caught up in the interpret tag.) Best of all was this interactive tester. I figured out most of what I figured out with this.

Considerations, before we start.

• The advantages of search plugins over keywords are the ability to share it through Mozilla and sometimes the searchbox seems mildly more usable. (I can’t offer a more reasonable explanation.) Keywords are, however, easier to write and “install.”
• This is the Mycroft way. The future, I guess, is with OpenSearch, which is compatible with both FF2 and IE7. It’s just as easy, so I’ll do another tutorial. meanwhile, see the docs.
• Other, perhaps easier and more straightforward ways of creating your plugin are:
  • Mycroft’s generator or submission tool.
  • The OpenSearchFox extension.
• Here I’m just going to explain how to very simply get a working search plugin built for a site you use. These are merely the bare essentials. These should work with Mozilla, Seamonkey, Firefox, Flock, IceWeasel, some Netscapes*, and so on. It’s even easier in Konqueror.

1. Go to the site you want to write a plugin for. While you’re here note the URL for the search page. This will be your “$SEARCH_URL” below.
2. Do a search for some term. Note the URL of the results page. On DSAL this is like:
   http://dsal.uchicago.edu/cgi-bin/philologic/search3advanced?dbname=steingass\
&query=talash&matchtype=exact&display=utf8
3. Break it up. First, take everything before the ‘?’. This is going to be your “$ACTION.”
   http://dsal.uchicago.edu/cgi-bin/philologic/search3advanced
   (You might think that for a plugin for Steingass, you would want everything up to ‘query,’ but that would result in an extra question mark which will break your search.)
4. Then break up and look at the “name=value” pairs:
   • dbname=steingass
   • query=talash
   • matchtype=exact
   • display=utf8

   Now, DSAL gives you a number of display and search options. But we want this to be as widely usable as possible, so we’re just gonna chop off the last two pairs there. You’ll probably run into a few options like that with whatever site you’re building for. The remaining pairs are going to be your “input” tags.

5. Now plug your details into this template.
   
<search
name="$PLUGIN_NAME"
description="$PLUGIN_DESCRIPTION"
action="$ACTION"
searchForm="$SEARCH_URL"
method="GET"
>

   • $PLUGIN_NAME is what will appear in the search box.
   • $PLUGIN_DESCRIPTION, well, you get it.
   • We figured out $ACTION before.
   • Same with $SEARCH_URL.
6. The syntax for the inputs is:
   <input name="$NAME" value="$VALUE">
   One of your inputs is going to be the one where we want to put in whatever the user types in the search box – i.e. the search term. In our case it was “query.” Whatever it is for your site, replace value="$VALUE"with user (no quotes) so it looks like:
   <input name="$NAME" user>
7. If you want to be nice to web masters, you can add this line to let them know this is how you’re searching:
   <input name="sourceid" value="Mozilla-search">
8. Now close your search tag:
   </search>
9. If the plugin is just for friends and family, you’re done. Test it in the validator. Then save it with a .src extension.
10. To install it, copy it into your search plugins folder – probably under your (local) Firefox profile, e.g. ~/.mozilla/firefox/SOMETHING_WEIRD.default/searchplugins, or C:\Documents and Settings\USER_NAME\Application Data\Mozilla\Firefox\Profiles\SOMETHING_WEIRD\searchplugins. (The latter is a guess. The last part might be different.) When you restart Firefox, it will be converted to xml, and you should see it in the search box.**

You can read the documentation if you find you might want to take advantage of other options such as the interpret tag – which tells the browser where to find results. If you want Mozilla to host it, there are some more things to add. Check out their guidelines for submission, as well as the aforementioned Quick Start. The examples – one simple, one advanced, are also really helpful.

You can try using Mycroft’s generator. I didn’t because so many of the fields made no sense until I read the documentation, an once I’d done that I already had this one written.
http://mycroft.mozdev.org/generator

*To work in Netscape 7, you need to add a line to the search tag that says:
version="7.1"
The Mycroft Quick Start guide uses 7.1 as the version number. The version number is supposed to be the last version of Netscape the plugin was tested with. This is apparently because Netscape (used to?) only allow plugins tested against the version in use. 7.1 was – I guess – the latest release at the time the Mycroft site was written. There was a 7.2. Netscape 8+ is based on Firefox, so I’ll venture a guess that this was fixed. So is this just for legacy Netscape? I don’t know. Probably. The blog I linked to just copied the docs. I’ll do the same. Does anyone use Netscape?

** Some plugins seem to end up in your local directory, and others in /usr/share/firefox/searchplugins or its equivalent. There doesn’t seem to be any rhyme or reason.