OpenSearch plugins for Firefox

1:18:00 PM 0 Comments



${FIREFOX_HOME}/searchplugins
${PROFILE}/searchplugins

default profile folder




  • On Windows Vista/XP/2000, the path is usually %AppData%\Mozilla\Firefox\Profiles\xxxxxxxx.default\,
    where xxxxxxxx is a random string of 8 characters. Just browse to
    C:\Documents and Settings\[User Name]\Application
    Data\Mozilla\Firefox\Profiles\ on Windows XP/2000 or C:\users\[User
    Name]\AppData\Roaming\Mozilla\Firefox\Profiles\ on Windows Vista, and
    the rest should be obvious.

  • On Windows 95/98/Me, the path is usually C:\WINDOWS\Application Data\Mozilla\Firefox\Profiles\xxxxxxxx.default\

  • On Linux, the path is usually ~/.mozilla/firefox/xxxxxxxx.default/

  • On Mac OS X, the path is usually ~/Library/Application Support/Firefox/Profiles/xxxxxxxx.default/


OpenSearch description file


The XML file describing a search engine is actually quite simple,
following the basic template below. Sections in bold need to be
customized based on the needs of the specific search engine plugin
you're writing.


<OpenSearchDescription xmlns="http://a9.com/-/spec/opensearch/1.1/"
                       xmlns:moz="http://www.mozilla.org/2006/browser/search/">
<ShortName>engineName</ShortName>
<Description>engineDescription</Description>
<InputEncoding>inputEncoding</InputEncoding>
<Image width="16" height="16" type="image/x-icon">data:image/x-icon;base64,imageData</Image>
<Url type="text/html" method="method" template="searchURL">
  <Param name="paramName1" value="paramValue1"/>
  ...
  <Param name="paramNameN" value="paramValueN"/>
</Url>
<Url type="application/x-suggestions+json" template="suggestionURL"/>
<moz:SearchForm>searchFormURL</moz:SearchForm>
</OpenSearchDescription>

ShortName A short name for the search engine. Restrictions: The value must contain 16 or fewer characters of plain text. The value must not contain HTML or other markup. Description A brief description of the search engine. Restrictions: The value must contain 1024 or fewer characters of plain text. The value must not contain HTML or other markup. InputEncoding The encoding to use for the data input to the search engine. Example: <InputEncoding>UTF-8</InputEncoding>. Image URI
to an icon representative of the search engine. When possible, search
engines should offer a 16x16 image of type "image/x-icon" and a 64x64
image of type "image/jpeg" or "image/png". The link may also use the data: URI scheme. One useful tool that you can use to construct the data to place here can be found here: The data: URI kitchen.
<Image height="16" width="16" type="image/x-icon">http://example.com/favicon.ico</Image>
  OR
<Image height="16" width="16">data:image/x-icon;base64,AAABAAEAEBAAA ... DAAA=</Image>

Firefox caches the icon as a base64 data: URI (search plug-ins are
stored in the profile's "searchplugins" folder). http: URIs are changed
to data: URIs when this is done. Url Describes the URL or URLs to use for the search. The method attribute indicates whether to use a GET or POST request to fetch the result. The template attribute indicates the base URL for the search query.
Note: Internet Explorer 7 does not support POST requests.

There are two URL types Firefox supports:
  • type="text/html" is used to specify the URL for the actual search query itself.
  • type="application/x-suggestions+json" is used to specify the URL to use for fetching search suggestions.

For either type of URL, you can use {searchTerms}
to substitute the search terms entered by the user in the search bar.
Other supported dynamic search parameters are described in OpenSearch 1.1 parameters.
For search suggestion queries, the specified URL template is used to
fetch a suggestion list in JavaScript Object Notation (JSON) format.
For details on how to implement search suggestion support on a server,
see Supporting search suggestions in search plugins.

Image:SearchSuggestionSample.png


Param The parameters that need to be passed in along with the search query, as key/value pairs. When specifying values, you can use {searchTerms} to insert the search terms entered by the user in the search bar.
Note: Internet Explorer 7 does not support this element.

SearchForm The URL to go
to to open up the search page at the site for which the plugin is
designed to search. This provides a way for Firefox to let the user
visit the web site directly.
Note: Since this element is Firefox-specific, and not part of the OpenSearch specification, we use the "moz:"
XML namespace prefix in the example above to ensure that other user
agents that don't support this element can safely ignore it.


Autodiscovery of search plugins


A web site that offers a search plugin can advertise it so that Firefox users can easily download and install the plugin.


To support autodiscovery, you simply need to add one line to the <head> section of your web page:


<link rel="search" type="application/opensearchdescription+xml" title="searchTitle" href="pluginURL">

Replace the italicized items as explained below:


searchTitle The name of the search
to perform, such as "Search MDC" or "Yahoo! Search". This value should
match your plugin file's ShortName. pluginURL The URL to the XML search plugin, from which the browser can download it.

If your site offers multiple search plugins, you can support autodiscovery for them all. For example:


<link rel="search" type="application/opensearchdescription+xml" title="MySite: By Author" href="http://www.mysite.com/mysiteauthor.xml">
<link rel="search" type="application/opensearchdescription+xml" title="MySite: By Title" href="http://www.mysite.com/mysitetitle.xml">

This way, your site can offer plugins to search both by author and by title as separate entities.


Supporting automatic updates for OpenSearch plugins




Firefox 3.1 note


This section covers a feature introduced in Firefox 3.1.





Starting in Firefox 3.1, OpenSearch plugins can be updated automatically.  To support this, they need to include an extra Url element of type "application/opensearchdescription+xml".  The rel attribute needs to be "self" and the template attribute needs to be the URL of the OpenSearch document to automatically update to.


For example:


<Url type="application/opensearchdescription+xml"
     rel="self"
     template="http://www.foo.com/mysearchdescription.xml" />

Troubleshooting Tips


If there is a mistake in your Search Plugin XML, you could run into
errors when adding a discovered plugin in Firefox 2. The error message
may not be entirely helpful, however, so the following tips could help
you find the problem.


  • Your server should serve OpenSearch plugins using the MIME type application/opensearchdescription+xml.
  • Be
    sure that your Search Plugin XML is well formed. You can check by
    loading the file directly into Firefox. Ampersands in the template URL
    need to be escaped with &amp; and tags need to be closed with a
    trailing slash or matching end tag.
  • The xmlns
    attribute is important, without it you could get an error message
    indicating that "Firefox could not download the search plugin from:
    (URL)".
  • Note that you must include a text/html URL — search plugins including only Atom or RSS URL types (which is valid, but Firefox doesn't support) will also generate the "could not download the search plugin" error.
  • Remotely fetched favicons must not be larger than 10KB (see
    bug 361923).

In addition, the search plugin service provides a logging mechanism that may be of use to plugin developers. Use about:config to set the pref 'browser.search.log' to true. Logging information will appear in Firefox's Error Console (Tools->Error Console) when search plugins are added.


Reference Material



Some say he’s half man half fish, others say he’s more of a seventy/thirty split. Either way he’s a fishy bastard.