Creating MozSearch plugins

  • Revision slug: Creating_MozSearch_plugins
  • Revision title: Creating MozSearch plugins
  • Revision id: 162451
  • Created:
  • Creator: Sheppy
  • Is current revision? No
  • Comment /* The plugin file */

Revision Content

Firefox 2.0 supports Amazon A9's OpenSearch format for creating search plugins.

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

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>
engineName
A short name for the search engine.
engineDescription
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.

Image:SearchSuggestionSample.png

imageData
Base-64 encoded 16x16 icon representative of the search engine.
method
The method to use for sending the search query: GET or POST.
searchURL
The base URL for the search query. The parameters described inside the <Url> element are appended to this URL.
paramName1 ... paramNameN
The names of each parameter that need to be passed in along with the search query.
paramValue1 ... paramValueN
The values for each of the parameters passed along with the search query. You can use {searchTerms} to insert the search terms entered by the user in the search box.
searchFormURL
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.

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}&go=Go"/>
<SearchForm>http://developer.mozilla.org/en/docs/</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.

Revision Source

<p>Firefox 2.0 supports Amazon A9's <a class="external" href="http://opensearch.a9.com/">OpenSearch</a> format for creating search plugins.
</p><p>A 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>
<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="paramName1"/&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>engineName</b>
</dt><dd> A short name for the search engine.
</dd></dl>
<dl><dt> <b>engineDescription</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>
<p><img alt="Image:SearchSuggestionSample.png" src="File:en/Media_Gallery/SearchSuggestionSample.png">
</p>
<dl><dt> <b>imageData</b>
</dt><dd> Base-64 encoded 16x16 icon representative of the search engine.
</dd></dl>
<dl><dt> <b>method</b>
</dt><dd> The method to use for sending the search query: <code>GET</code> or <code>POST</code>.
</dd></dl>
<dl><dt> <b>searchURL</b>
</dt><dd> The base URL for the search query.  The parameters described inside the <code>&lt;Url&gt;</code> element are appended to this URL.
</dd></dl>
<dl><dt> <b>paramName1</b> ... <b>paramNameN</b>
</dt><dd> The names of each parameter that need to be passed in along with the search query.
</dd></dl>
<dl><dt> <b>paramValue1</b> ... <b>paramValueN</b>
</dt><dd> The values for each of the parameters passed along with the search query.  You can use <code>{searchTerms}</code> to insert the search terms entered by the user in the search box.
</dd></dl>
<dl><dt> <b>searchFormURL</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="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}&amp;go=Go"/&gt;
&lt;SearchForm&gt;http://developer.mozilla.org/en/docs/&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>
Revert to this revision