Creating MozSearch plugins

  • Revision slug: Creating_MozSearch_plugins
  • Revision title: Creating MozSearch plugins
  • Revision id: 162468
  • Created:
  • Creator: Nickolay
  • Is current revision? No
  • Comment SuggestionURL -> SuggestionUrl, bug 340444

Revision Content

Firefox 2 supports MozSearch, a simplified form of Amazon A9's OpenSearch format for creating search plugins. OpenSearch plugins are also supported; see the OpenSearch site for details.

A MozSearch search plugin is an XML file that describes the search engine, its URL, and the parameters that need to be passed to that URL.

Note: Keep in mind that MozSearch is specific to Firefox; if you want to write a plugin that's compatible with other browsers, you may wish to use the standard OpenSearch system. Fortunately, the two formats are very similar and it's easy to switch back and forth depending on your needs.

The plugin file

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

<SearchPlugin xmlns="http://www.mozilla.org/2006/browser/search/">
<ShortName>engineName</ShortName>
<Description>engineDescription</Description>
<InputEncoding>inputEncoding</InputEncoding>
<SuggestionUrl>suggestionURL</SuggestionUrl>
<Image width="16" height="16">data:image/x-icon;base64,imageData</image>
<Url type="text/plain" method="method" template="searchURL">
  <Param name="paramName1" value="paramName1"/>
  ...
  <Param name="paramNameN" value="paramValueN"/>
</Url>
<SearchForm>searchFormURL</SearchForm> 
</SearchPlugin>
ShortName
A short name for the search engine.
Description
A brief description of the search engine.
InputEncoding
The encoding to use for the data input to the search engine.
SuggestionUrl
If the search engine supports making find-as-you-type suggestions, this URL is used to do lookups based on the current content of the search box while typing to provide a drop-down menu listing the returned search results. This is an optional element; if the search engine doesn't support find-as-you-type suggestions, you can leave it out.
In Firefox 2 Alphas this element used to be called SuggestionURL. It has been changed to SuggestionUrl for consistency with the Url element for Firefox 2 Beta 1 ({{template.Bug(340444)}})

Image:SearchSuggestionSample.png

Image
Base-64 encoded 16x16 icon representative of the search engine. One useful tool that you can use to construct the data to place here can be found here: The data: URI kitchen.
Url
Describes the URL to use for the search query. 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.
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 box.
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.

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".
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.

Example: searching Yahoo!

The following XML is the bundled Firefox 2 search plugin for searching using Yahoo!:

<SearchPlugin xmlns="http://www.mozilla.org/2006/browser/search/">
<ShortName>Yahoo</ShortName>
<Description>Yahoo Search</Description>
<InputEncoding>UTF-8</InputEncoding>
<SuggestionUrl>http://ff.search.yahoo.com/gossip?output=fxjson&command=</SuggestionUrl>
<Image width="16" height="16">data:image/x-icon;base64,R0lGODlhEAAQAJECAP8AAAAAAP///wAAACH5BAEAAAIALAAAAAAQABAAAAIplI+py+0NogQuyBDEnEd2kHkfFWUamEzmpZSfmaIHPHrRguUm/fT+UwAAOw==</Image>
<Url type="text/html" method="GET" template="http://search.yahoo.com/search">
  <Param name="p" value="{searchTerms}"/>
  <Param name="ei" value="UTF-8"/>
  <Param name="fr" value="moz2"/>
</Url>
<SearchForm>http://search.yahoo.com/</SearchForm>
</SearchPlugin>

Let's say the user chooses to use the Yahoo! search engine plugin and enters "mozilla" in the search box and presses the enter key. Firefox will use the above search engine description to construct the following search URL:

http://search.yahoo.com/search?p=mozilla&ei=UTF-8&fr=moz2

If the user clicks the magnifying glass icon in the search bar, or chooses the Web Search option in the Tools menu when the search bar isn't visible, the browser will take them to <tt>http://search.yahoo.com/</tt>, the value of the <SearchForm> element.

Example: searching MDC

This plugin lets you easily search the Mozilla Developer Center web site.

<SearchPlugin xmlns="http://www.mozilla.org/2006/browser/search/">
<ShortName>MDC</ShortName>
<Description>Mozilla Developer Center search</Description>
<InputEncoding>UTF-8</InputEncoding>
<Image width="16" height="16">data:image/x-icon;base64,iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAYAAAAf8%2F9hAAAABGdBTUEAAK%2FINwWK6QAAABl0RVh0U29mdHdhcmUAQWRvYmUgSW1hZ2VSZWFkeXHJZTwAAAHWSURBVHjaYvz%2F%2Fz8DJQAggJiQOe%2Ffv2fv7Oz8rays%2FN%2BVkfG%2FiYnJfyD%2F1%2BrVq7ffu3dPFpsBAAHEAHIBCJ85c8bN2Nj4vwsDw%2F8zQLwKiO8CcRoQu0DxqlWrdsHUwzBAAIGJmTNnPgYa9j8UqhFElwPxf2MIDeIrKSn9FwSJoRkAEEAM0DD4DzMAyPi%2FG%2BQKY4hh5WAXGf8PDQ0FGwJ22d27CjADAAIIrLmjo%2BMXA9R2kAHvGBA2wwx6B8W7od6CeQcggKCmCEL8bgwxYCbUIGTDVkHDBia%2BCuotgACCueD3TDQN75D4xmAvCoK9ARMHBzAw0AECiBHkAlC0Mdy7x9ABNA3obAZXIAa6iKEcGlMVQHwWyjYuL2d4v2cPg8vZswx7gHyAAAK7AOif7SAbOqCmn4Ha3AHFsIDtgPq%2FvLz8P4MSkJ2W9h8ggBjevXvHDo4FQUQg%2FkdypqCg4H8lUIACnQ%2FSOBMYI8bAsAJFPcj1AAEEjwVQqLpAbXmH5BJjqI0gi9DTAAgDBBCcAVLkgmQ7yKCZxpCQxqUZhAECCJ4XgMl493ug21ZD%2BaDAXH0WLM4A9MZPXJkJIIAwTAR5pQMalaCABQUULttBGCCAGCnNzgABBgAMJ5THwGvJLAAAAABJRU5ErkJggg%3D%3D</Image>
<Url type="text/html" method="GET" template="http://developer.mozilla.org/en/docs/Special:Search?search={searchTerms}"/>
<SearchForm>http://developer.mozilla.org/en/docs/Special:Search</SearchForm> 
</SearchPlugin>

Notice in this case that instead of using <Param> to define parameters to the search engine, they're simply embedded inside the template URL. This is actually the preferred way to do things when using GET as the method. <Param> should be used for POST.


Troubleshooting Tips

If there is a mistake in your Search Plugin XML, you could run into errors when adding an discovered plugin in Firefox (Bon Echo) Alpha 3. The error message may not be entirely helpful, however, the following tips could help in finding the problem.

  • 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 "Bon Echo could not download the plugin from (URL)"

OpenSearch

The OpenSearch Description format is similar to the Mozilla SearchPlugin format. The main difference is the root element and XML namespace.

<xml version="1.0"  encoding="UTF-8"?>
<OpenSearchDescription xmlns="http://a9.com/-/spec/opensearch/1.1/">
...
</OpenSearchDescription>

Reference Material

Revision Source

<p>Firefox 2 supports MozSearch, a simplified form of Amazon A9's OpenSearch format for creating search plugins.  OpenSearch plugins are also supported; see the <a class="external" href="http://opensearch.a9.com/">OpenSearch</a> site for details.
</p><p>A MozSearch search plugin is an XML file that describes the search engine, its URL, and the parameters that need to be passed to that URL.
</p>
<div class="note"><b>Note:</b> Keep in mind that MozSearch is specific to Firefox; if you want to write a plugin that's compatible with other browsers, you may wish to use the standard OpenSearch system.  Fortunately, the two formats are very similar and it's easy to switch back and forth depending on your needs.</div>
<h2 name="The_plugin_file">The plugin file</h2>
<p>The XML file describing a search engine is actually quite simple, following the basic template below.  Sections in italics need to be customized based on the needs of the specific search engine plugin you're writing.
</p>
<pre class="eval">&lt;SearchPlugin xmlns="<span class="plain">http://www.mozilla.org/2006/browser/search/</span>"&gt;
&lt;ShortName&gt;<i>engineName</i>&lt;/ShortName&gt;
&lt;Description&gt;<i>engineDescription</i>&lt;/Description&gt;
&lt;InputEncoding&gt;<i>inputEncoding</i>&lt;/InputEncoding&gt;
&lt;SuggestionUrl&gt;<i>suggestionURL</i>&lt;/SuggestionUrl&gt;
&lt;Image width="16" height="16"&gt;data:image/x-icon;base64,<i>imageData</i>&lt;/image&gt;
&lt;Url type="text/plain" method="<i>method</i>" template="<i>searchURL</i>"&gt;
  &lt;Param name="<i>paramName1</i>" value="<i>paramName1</i>"/&gt;
  ...
  &lt;Param name="<i>paramNameN</i>" value="<i>paramValueN</i>"/&gt;
&lt;/Url&gt;
&lt;SearchForm&gt;<i>searchFormURL</i>&lt;/SearchForm&gt; 
&lt;/SearchPlugin&gt;
</pre>
<dl><dt> <b>ShortName</b>
</dt><dd> A short name for the search engine.
</dd></dl>
<dl><dt> <b>Description</b>
</dt><dd> A brief description of the search engine.
</dd></dl>
<dl><dt> <b>InputEncoding</b>
</dt><dd> The encoding to use for the data input to the search engine.
</dd></dl>
<dl><dt> <b>SuggestionUrl</b>
</dt><dd> If the search engine supports making find-as-you-type suggestions, this URL is used to do lookups based on the current content of the search box while typing to provide a drop-down menu listing the returned search results.  This is an optional element; if the search engine doesn't support find-as-you-type suggestions, you can leave it out.
</dd></dl>
<div class="note">In Firefox 2 Alphas this element used to be called <code>SuggestionURL</code>. It has been changed to <code>SuggestionUrl</code> for consistency with the <code>Url</code> element for Firefox 2 Beta 1 ({{template.Bug(340444)}})</div>
<p><img alt="Image:SearchSuggestionSample.png" src="File:en/Media_Gallery/SearchSuggestionSample.png">
</p>
<dl><dt> <b>Image</b>
</dt><dd> Base-64 encoded 16x16 icon representative of the search engine.  One useful tool that you can use to construct the data to place here can be found here: <a class="external" href="http://software.hixie.ch/utilities/cgi/data/data">The data: URI kitchen</a>.
</dd></dl>
<dl><dt> <b>Url</b>
</dt><dd> Describes the URL to use for the search query.  The <code>method</code> attribute indicates whether to use a <code>GET</code> or <code>POST</code> request to fetch the result.  The <code>template</code> attribute indicates the base URL for the search query.
</dd></dl>
<dl><dt> <b>Param</b>
</dt><dd> The parameters that need to be passed in along with the search query, as key/value pairs.  When specifying values, you can use <code>{searchTerms}</code> to insert the search terms entered by the user in the search box.
</dd></dl>
<dl><dt> <b>SearchForm</b>
</dt><dd> 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.
</dd></dl>
<h2 name="Autodiscovery_of_search_plugins">Autodiscovery of search plugins</h2>
<p>A web site that offers a search plugin can advertise it so that Firefox users can easily download and install the plugin.
</p><p>To support autodiscovery, you simply need to add one line to the <code>&lt;HEAD&gt;</code> section of your web page:
</p>
<pre class="eval">&lt;link rel="search" type="application/opensearchdescription+xml" title="<i>searchTitle</i>" href="<i>pluginURL</i>"&gt;
</pre>
<p>Replace the italicized items as explained below:
</p>
<dl><dt> <b>searchTitle</b>
</dt><dd> The name of the search to perform, such as "Search MDC" or "Yahoo! Search".
</dd></dl>
<dl><dt> <b>pluginURL</b>
</dt><dd> The URL to the XML search plugin, from which the browser can download it.
</dd></dl>
<p>If your site offers multiple search plugins, you can support autodiscovery for them all.  For example:
</p>
<pre class="eval">&lt;link rel="search" type="application/opensearchdescription+xml" title="MySite: By Author" href="http://www.mysite.com/mysiteauthor.xml"&gt;
&lt;link rel="search" type="application/opensearchdescription+xml" title="MySite: By Title" href="http://www.mysite.com/mysitetitle.xml"&gt;
</pre>
<p>This way, your site can offer plugins to search both by author and by title as separate entities.
</p>
<h2 name="Example:_searching_Yahoo.21">Example: searching Yahoo!</h2>
<p>The following XML is the bundled Firefox 2 search plugin for searching using Yahoo!:
</p>
<pre>&lt;SearchPlugin xmlns="http://www.mozilla.org/2006/browser/search/"&gt;
&lt;ShortName&gt;Yahoo&lt;/ShortName&gt;
&lt;Description&gt;Yahoo Search&lt;/Description&gt;
&lt;InputEncoding&gt;UTF-8&lt;/InputEncoding&gt;
&lt;SuggestionUrl&gt;http://ff.search.yahoo.com/gossip?output=fxjson&amp;command=&lt;/SuggestionUrl&gt;
&lt;Image width="16" height="16"&gt;data:image/x-icon;base64,R0lGODlhEAAQAJECAP8AAAAAAP///wAAACH5BAEAAAIALAAAAAAQABAAAAIplI+py+0NogQuyBDEnEd2kHkfFWUamEzmpZSfmaIHPHrRguUm/fT+UwAAOw==&lt;/Image&gt;
&lt;Url type="text/html" method="GET" template="http://search.yahoo.com/search"&gt;
  &lt;Param name="p" value="{searchTerms}"/&gt;
  &lt;Param name="ei" value="UTF-8"/&gt;
  &lt;Param name="fr" value="moz2"/&gt;
&lt;/Url&gt;
&lt;SearchForm&gt;http://search.yahoo.com/&lt;/SearchForm&gt;
&lt;/SearchPlugin&gt;
</pre>
<p>Let's say the user chooses to use the Yahoo! search engine plugin and enters "mozilla" in the search box and presses the enter key.  Firefox will use the above search engine description to construct the following search URL:
</p>
<pre class="eval"><span class="plain">http://search.yahoo.com/search?p=mozilla&amp;ei=UTF-8&amp;fr=moz2</span>
</pre>
<p>If the user clicks the magnifying glass icon in the search bar, or chooses the Web Search option in the Tools menu when the search bar isn't visible, the browser will take them to <tt><span class="plain">http://search.yahoo.com/</span></tt>, the value of the <code>&lt;SearchForm&gt;</code> element.
</p>
<h2 name="Example:_searching_MDC">Example: searching MDC</h2>
<p>This plugin lets you easily search the Mozilla Developer Center web site.
</p>
<pre>&lt;SearchPlugin xmlns="http://www.mozilla.org/2006/browser/search/"&gt;
&lt;ShortName&gt;MDC&lt;/ShortName&gt;
&lt;Description&gt;Mozilla Developer Center search&lt;/Description&gt;
&lt;InputEncoding&gt;UTF-8&lt;/InputEncoding&gt;
&lt;Image width="16" height="16"&gt;data:image/x-icon;base64,iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAYAAAAf8%2F9hAAAABGdBTUEAAK%2FINwWK6QAAABl0RVh0U29mdHdhcmUAQWRvYmUgSW1hZ2VSZWFkeXHJZTwAAAHWSURBVHjaYvz%2F%2Fz8DJQAggJiQOe%2Ffv2fv7Oz8rays%2FN%2BVkfG%2FiYnJfyD%2F1%2BrVq7ffu3dPFpsBAAHEAHIBCJ85c8bN2Nj4vwsDw%2F8zQLwKiO8CcRoQu0DxqlWrdsHUwzBAAIGJmTNnPgYa9j8UqhFElwPxf2MIDeIrKSn9FwSJoRkAEEAM0DD4DzMAyPi%2FG%2BQKY4hh5WAXGf8PDQ0FGwJ22d27CjADAAIIrLmjo%2BMXA9R2kAHvGBA2wwx6B8W7od6CeQcggKCmCEL8bgwxYCbUIGTDVkHDBia%2BCuotgACCueD3TDQN75D4xmAvCoK9ARMHBzAw0AECiBHkAlC0Mdy7x9ABNA3obAZXIAa6iKEcGlMVQHwWyjYuL2d4v2cPg8vZswx7gHyAAAK7AOif7SAbOqCmn4Ha3AHFsIDtgPq%2FvLz8P4MSkJ2W9h8ggBjevXvHDo4FQUQg%2FkdypqCg4H8lUIACnQ%2FSOBMYI8bAsAJFPcj1AAEEjwVQqLpAbXmH5BJjqI0gi9DTAAgDBBCcAVLkgmQ7yKCZxpCQxqUZhAECCJ4XgMl493ug21ZD%2BaDAXH0WLM4A9MZPXJkJIIAwTAR5pQMalaCABQUULttBGCCAGCnNzgABBgAMJ5THwGvJLAAAAABJRU5ErkJggg%3D%3D&lt;/Image&gt;
&lt;Url type="text/html" method="GET" template="http://developer.mozilla.org/en/docs/Special:Search?search={searchTerms}"/&gt;
&lt;SearchForm&gt;http://developer.mozilla.org/en/docs/Special:Search&lt;/SearchForm&gt; 
&lt;/SearchPlugin&gt;
</pre>
<p>Notice in this case that instead of using <code>&lt;Param&gt;</code> to define parameters to the search engine, they're simply embedded inside the template URL.  This is actually the preferred way to do things when using <code>GET</code> as the method.  <code>&lt;Param&gt;</code> should be used for <code>POST</code>.
</p><p><br>
</p>
<h2 name="Troubleshooting_Tips">Troubleshooting Tips</h2>
<p>If there is a mistake in your Search Plugin XML, you could run into errors when adding an discovered plugin in Firefox (Bon Echo) Alpha 3. The error message may not be entirely helpful, however, the following tips could help in finding the problem.
</p>
<ul><li>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;amp; and tags need to be closed with a trailing slash or matching end tag.
</li><li>The <code>xmlns</code> attribute is important, without it you could get an error message indicating that "Bon Echo could not download the plugin from (URL)"
</li></ul>
<h2 name="OpenSearch">OpenSearch</h2>
<p>The OpenSearch Description format is similar to the Mozilla SearchPlugin format. The main difference is the root element and XML namespace.
</p>
<pre>&lt;xml version="1.0"  encoding="UTF-8"?&gt;
&lt;OpenSearchDescription xmlns="http://a9.com/-/spec/opensearch/1.1/"&gt;
...
&lt;/OpenSearchDescription&gt;
</pre>
<h2 name="Reference_Material">Reference Material</h2>
<ul><li>A9.com <a class="external" href="http://opensearch.a9.com/">OpenSearch Documentation</a>
</li><li>Technorati.com has a <a class="external" href="http://technorati.com/osd.xml">working osd.xml</a>
</li><li>More on Autodiscovery difficulties at bugzilla {{template.Bug(340208)}}
</li><li><a class="external" href="http://en.wikipedia.org/wiki/Data:_URL">Data:</a> URI scheme
</li></ul>
Revert to this revision