Firefox supports the OpenSearch description format for search plugins. OpenSearch plugins are also compatible with Internet Explorer, Safari, and Chrome.
Firefox also supports additional features not included in the OpenSearch standard, such as search suggestions and the <SearchForm>
element. This article focuses on creating OpenSearch-compatible search plugins that support these additional Firefox features.
OpenSearch description files can be advertised as described in Autodiscovery of search plugins, and can be installed programmatically as described in Adding search engines from web pages.
OpenSearch description file
The XML file describing a search engine follows the basic template below. Sections in bold should be customized for the specific plugin you're writing.
<OpenSearchDescription xmlns="http://a9.com/-/spec/opensearch/1.1/" xmlns:moz="http://www.mozilla.org/2006/browser/search/"> <ShortName>SNK</ShortName> <Description>Search engine full name and summary</Description> <InputEncoding>UTF-8</InputEncoding> <Image width="16" height="16" type="image/x-icon">data:image/x-icon;base64,AAABAAEAEBAAA ...</Image> <Url type="text/html" template="searchURL"> <Param name="key name" value="{searchTerms}"/> ... <Param name="key name" value="parameter value"/> </Url> <Url type="application/x-suggestions+json" template="suggestionURL"/> <moz:SearchForm>http://example.com/search</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 character 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 16×16 image of type "image/x-icon" and a 64×64 image of type
image/jpeg
orimage/png
. The URI may also use thedata:
URI scheme. You can generate adata:
URI from an icon file at Thedata:
URI kitchen.<Image height="16" width="16" type="image/x-icon">https://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 todata:
URIs when this is done.Note: For icons loaded remotely (i.e. fromhttps://
URIs as opposed todata:
URIs), Firefox will reject icons larger than 10 kilobytes in size. - Url
- Describes the URL or URLs to use for the search. The
method
attribute indicates whether to use aGET
orPOST
request to fetch the result. Thetemplate
attribute indicates the base URL for the search query. - Firefox supports three URL types:
type="text/html"
specifies the URL for the actual search query.type="application/x-suggestions+json"
specifies the URL for fetching search suggestions.type="application/x-moz-keywordsearch"
specifies the URL used when a keyword search is entered in the location bar. This is supported only in Firefox.
For these URL types, you can use
{searchTerms}
to substitute the search terms entered by the user in the search bar or location 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.
- 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. - 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
Web sites offering search plugins can advertise them so Firefox users can easily download and install the plugins.
To support autodiscovery, add a <link>
element for each plugin to the <head>
section of your web page:
<link rel="search" type="application/opensearchdescription+xml" title="searchTitle" href="pluginURL">
Replace the bolded 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://example.com/mysiteauthor.xml"> <link rel="search" type="application/opensearchdescription+xml" title="MySite: By Title" href="http://example.com/mysitetitle.xml">
This way, your site can offer plugins to search by author or by title as separate entities.
Supporting automatic updates for OpenSearch plugins
OpenSearch plugins can be updated automatically. To support this, 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://example.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. If the error message isn't be helpful, the following tips could help you find the problem.
- Your server should serve OpenSearch plugins using
Content-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
&
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". - 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
- OpenSearch Documentation, OpenSearch Documentation about the Url and Param element
- imdb.com has a working osd.xml
data:
URI scheme- OpenSearch Plugin Generator
- Ready2Search - create OpenSearch plugins. Customized Search through Ready2Search