Creating MozSearch plugins

  • Revision slug: Creating_MozSearch_plugins
  • Revision title: Creating MozSearch plugins
  • Revision id: 162483
  • Created:
  • Creator: Dazzle
  • Is current revision? No
  • Comment /* Reference Material */

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>
<Image width="16" height="16">data:image/x-icon;base64,imageData</image>
<Url type="text/html" method="method" template="searchURL">
  <Param name="paramName1" value="paramName1"/>
  ...
  <Param name="paramNameN" value="paramValueN"/>
</Url>
<Url type="application/x-suggestions+json" template="suggestionURL"/>
<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.
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 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.
There are two URL types you can specify:
  • 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.
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.
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)"

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.

OpenSearch

Firefox 2 also supports Amazon A9's OpenSearch format for sharing search results. If you write an XML plugin using the OpenSearch description syntax, it can be dropped into the <tt>searchengines</tt> directory in a user's profile, an application folder, or an installation bundle to add support for that search engine.

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

{{ wiki.languages( { "ca": "ca/Creaci\u00f3_de_connectors_MozSearch", "ja": "ja/Creating_MozSearch_plugins", "it": "it/Creare_Plugin_MozSearch" } ) }}

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;Image width="16" height="16"&gt;data:image/x-icon;base64,<i>imageData</i>&lt;/image&gt;
&lt;Url type="text/html" 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;Url type="application/x-suggestions+json" template="<i>suggestionURL</i>"/&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>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 or URLs to use for the search.  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><dd> There are two URL types you can specify:
</dd></dl>
<ul><li> <code>type="text/html"</code> is used to specify the URL for the actual search query itself.
</li><li> <code>type="application/x-suggestions+json"</code> is used to specify the URL to use for fetching search suggestions.
</li></ul>
<dl><dd> For either type of URL, you can use <code>{searchTerms}</code> to substitute the search terms entered by the user in the search bar.
</dd></dl>
<dl><dd> 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 <a href="en/Supporting_search_suggestions_in_search_plugins">Supporting search suggestions in search plugins</a>.
</dd></dl>
<p><img alt="Image:SearchSuggestionSample.png" src="File:en/Media_Gallery/SearchSuggestionSample.png">
</p>
<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 bar.
</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>
<p>In addition, the search plugin service provides a logging mechanism that may be of use to plugin developers. Use <i>about:config</i> to set the pref '<code>browser.search.log</code>' to <code>true</code>. Logging information will appear in Firefox's <a href="en/JavaScript_Console">Error Console</a> (Tools-&gt;Error Console) when search plugins are added.
</p>
<h2 name="OpenSearch">OpenSearch</h2>
<p><a href="en/Firefox_2">Firefox 2</a> also supports Amazon A9's <a class="external" href="http://opensearch.a9.com/">OpenSearch</a> format for sharing search results.  If you write an XML plugin using the <a class="external" href="http://opensearch.a9.com/spec/1.1/description/">OpenSearch description syntax</a>, it can be dropped into the <tt>searchengines</tt> directory in a <a class="external" href="http://www.mozilla.org/support/firefox/profile">user's profile</a>, an application folder, or an <a href="en/Bundles">installation bundle</a> to add support for that search engine.
</p><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><li><a class="external" href="http://www.searchplugins.net">searchplugins.net</a> - create OpenSearch plugins for use with Firefox2. <a class="external" href="http://www.searchplugins.net/pluginlist.aspx">List of generated search plugins</a>
</li></ul>
{{ wiki.languages( { "ca": "ca/Creaci\u00f3_de_connectors_MozSearch", "ja": "ja/Creating_MozSearch_plugins", "it": "it/Creare_Plugin_MozSearch" } ) }}
Revert to this revision