Do you frequently use the Google, Wikipedia, and other search boxes in Firefox, typically in the top right of the window? Ever wanted to add your own for a site that isn't on the directory? Here's a quick and dirty guide to creating your own Firefox search engine plugin, using the api.jquery.com search as an example.

Tested on: Firefox 3.6 (Windows 7)

The Goal

Create a search engine plugin, enabling you to search the jQuery API documentation in a quick and easy way.

First step

Close all windows of Firefox if it is running.

Finding a sample file

Find google.xml in your Firefox search plugins directory, in my case C:\Program Files\Mozilla Firefox\searchplugins\google.xml. Open it in your favorite text editor or IDE.

You should see something like this:

<SearchPlugin xmlns="http://www.mozilla.org/2006/browser/search/">
<ShortName>Google</ShortName>
<Description>Google Search</Description>
<InputEncoding>UTF-8</InputEncoding>
<Image width="16" height="16">data:image/png;base64,AAABAAEAEBAAAAEAGABoAwAAFgAAACgAAAAQAAAAI
AAAAAEAGAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAADs9Pt8xetPtu9FsfFNtu%2BTzvb2%2B%2Fne4dFJeBw0egA%2F
fAJAfAA8ewBBegAAAAD%2B%2FPtft98Mp%2BwWsfAVsvEbs%2FQeqvF8xO7%2F%2F%2F63yqkxdgM7gwE%2FggM%2BfQA%2B
egBDeQDe7PIbotgQufcMufEPtfIPsvAbs%2FQvq%2Bfz%2Bf%2F%2B%2B%2FZKhR05hgBBhQI8hgBAgAI9ewD0%2B%2Fg3
pswAtO8Cxf4Kw%2FsJvvYAqupKsNv%2B%2Fv7%2F%2FP5VkSU0iQA7jQA9hgBDgQU%2BfQH%2F%2Ff%2FQ6fM4sM4KsN8At
eMCruIqqdbZ7PH8%2Fv%2Fg6Nc%2Fhg05kAA8jAM9iQI%2BhQA%2BgQDQu6b97uv%2F%2F%2F7V8Pqw3eiWz97q8%2Ff%2F%2F
%2F%2F7%2FPptpkkqjQE4kwA7kAA5iwI8iAA8hQCOSSKdXjiyflbAkG7u2s%2F%2B%2F%2F39%2F%2F7r8utrqEYtjQE8lgA7
kwA7kwA9jwA9igA9hACiWSekVRyeSgiYSBHx6N%2F%2B%2Fv7k7OFRmiYtlAA5lwI7lwI4lAA7kgI9jwE9iwI4iQCoVhWcTx
Cmb0K%2BooT8%2Fv%2F7%2F%2F%2FJ2r8fdwI1mwA3mQA3mgA8lAE8lAE4jwA9iwE%2BhwGfXifWvqz%2B%2Ff%2F58u%2Fev
6Dt4tr%2B%2F%2F2ZuIUsggA7mgM6mAM3lgA5lgA6kQE%2FkwBChwHt4dv%2F%2F%2F728ei1bCi7VAC5XQ7kz7n%2F%2F%2F
6bsZkgcB03lQA9lgM7kwA2iQktZToPK4r9%2F%2F%2F9%2F%2F%2FSqYK5UwDKZAS9WALIkFn%2B%2F%2F3%2F%2BP8oKccGG
cIRJrERILYFEMwAAuEAAdX%2F%2Ff7%2F%2FP%2B%2BfDvGXQLIZgLEWgLOjlf7%2F%2F%2F%2F%2F%2F9QU90EAPQAAf8DAP
0AAfMAAOUDAtr%2F%2F%2F%2F7%2B%2Fu2bCTIYwDPZgDBWQDSr4P%2F%2Fv%2F%2F%2FP5GRuABAPkAA%2FwBAfkDAPAAAes
AAN%2F%2F%2B%2Fz%2F%2F%2F64g1C5VwDMYwK8Yg7y5tz8%2Fv%2FV1PYKDOcAAP0DAf4AAf0AAfYEAOwAAuAAAAD%2F%2FP
vi28ymXyChTATRrIb8%2F%2F3v8fk6P8MAAdUCAvoAAP0CAP0AAfYAAO4AAACAAQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAACAAQAA</Image>
<Url type="application/x-suggestions+json" method="GET" template="http://suggestqueries.google.com/complete/search?output=firefox&amp;client=firefox&amp;hl={moz:locale}&amp;q={searchTerms}"/>
<Url type="text/html" method="GET" template="http://www.google.com/search">
  <Param name="q" value="{searchTerms}"/>
  <Param name="ie" value="utf-8"/>
  <Param name="oe" value="utf-8"/>
  <Param name="aq" value="t"/>
  <!-- Dynamic parameters -->
  <Param name="rls" value="{moz:distributionID}:{moz:locale}:{moz:official}"/>
  <MozParam name="client" condition="defaultEngine" trueValue="firefox-a" falseValue="firefox"/>
</Url>
<SearchForm>http://www.google.com/firefox</SearchForm>
</SearchPlugin>

Changing the file

There's a few things going on here, but for our final product there are only a few important tags we need to keep:

• <Image> This tag is used to store the image data for the little icon you can assign to your search engine provider plugin. In this case, it is a Base64-encoded version of the Google logo.

  Since it would be nice to have the jQuery logo for our plugin, we'll create our own icon and base64 encode it.
  I simply went to jQuery.com, took a screenshot of my Firefox window, and cut-out the 16x16 favicon they're using. I saved the image as a PNG in my image editor.

  To get a Base64 string representation of my icon, I used http://www.motobit.com/util/base64-decoder-encoder.asp

  Paste the string into your xml file, after 'data:image/png;base64,'. Check the final XML posted below if you're unsure.

• <Url> This is the URL to which we want to submit our query. The search plugin just constructs a search URL with a GET query. Using a sample query URL such as http://api.jquery.com/?s=toggle, we can quickly figure out the parameter values. In our case, we'll change the 'template' attribute to http://api.jquery.com, and the rest can remain as is.
• <Param> We only need one parameter to be sent to the jQuery API search: s. So, we'll change the name attribute and leave the value attribute untouched.
• <SearchForm> I simply changed this to http://api.jquery.com

The finished plugin

After the changes, we're left with something like this.

<SearchPlugin xmlns="http://www.mozilla.org/2006/browser/search/">
<ShortName>jQuery API</ShortName>
<Description>jQuery API Search</Description>
<InputEncoding>UTF-8</InputEncoding>
<Image width="16" height="16">data:image/png;base64,iVBORw0KGgoAAAANSUhEUg
AAABAAAAAQCAMAAAAoLQ9TAAAAGXRFWHRTb2Z0d2FyZQBBZG9iZSBJbWFnZVJlYWR5ccllPAAA
AYBQTFRFCxUmCxUnChQkDRwvDhstChEiDRkrCxYnNYStCxQmChQmGDpTT7fhK22VDyE0JFd4T7
bhKGSJQ6HLK2iOKmaNDyAzLnCXUrzlRqfRTLPdGDtVHUFdSq/ZFTNMH0trLnObDh4ySKvWGTxY
Dh4zQJ3HCRAgPZjDEixDESY8Ei5EIEtrPJW/PJS/ULnjJ2GFFS5EGTtXEic8ChgpDyI2FzhQLn
CZULvjI1V1QJnEIVBwI1RzNoewFjBJOI22Dh4xDRYpJVh5OImyMn2nEStARqjSS63XR6rVHENf
P5vGCREhDh4wP5rFGzxWTLPeH0lpK2uSRKPNChgqPZbBDRosKWaKGThSRKXPDRsvDx8zOYu0ES
Y7ESU6HENgGT5ZDRYqQZ3IChUmHkloHERgHUVjCxQkNICpDRgrESlAJl2ADyU6R6nTGDZPTLHb
KmWMGDxXR6vWECQ5ESM3PZS+ChEkGDlTFC5ENoWvDyA1Sq7XESk/DRstDRgqDhsvCxYpDh0wDh
0vUXyXDgAAAP9JREFUeNokj1OXBDEYBb/uaWtse2Zt27Zt25t0kr++PWfr6Z77VAUu5iAITAjW
BnMBoza1rQqOPV1RBwYMWVTqaxYDS9z/sZprkctKkPdeziJKbQbfSlWNz7welVce2965vR04Le
Q5/ecMyLSvwfSnEGxE9rHle0OYtLq95/Y6+BdzstYUHpvjiSYW2z9hpCst2ttKeK2ugvIH5jh0
JLK6KmVCCWNivjCoE5BGG3t+TxCXvAktpzLqEAzHnj2lTZEQnueLcHgLTHM/eO7MJJU5aSDdjY
Ex6N0yjGx9/1cpEsCCE0cvqp3Hk9Ho1G4cHPVaPoaX+4WPa0Kc/D8BBgA8skGJMRxNdAAAAAB
JRU5ErkJggg==</Image>
<Url type="text/html" method="GET" template="http://api.jquery.com/">
  <Param name="s" value="{searchTerms}"/>
</Url>
<SearchForm>http://api.jquery.com/</SearchForm>
</SearchPlugin>

(Note that the Base64-encoded string for the image has been formatted to fit the post; make sure your string is all on one line to avoid issues.)

Save/move your xml file to the search plugin folder, such as C:\Program Files\Mozilla Firefox\searchplugins\

Start Firefox and you should now be able to pick your search engine provider in the search widget.