Revision 182716 of Supporting search suggestions in search plugins

<p>MozSearch supports search suggestions; as the user types in the search bar, <a href="en/Firefox_2">Firefox 2</a> queries the URL specified by the search engine plugin to fetch live search suggestions.
</p><p>Once the list has been retrieved, it's displayed in a popup box that appears under the search bar, which lets the user select a suggested search term.  If the user continues to type, a new set of suggestions is requested from the search engine, and the displayed list is refreshed.
</p><p>The Yahoo and Google search plugins included with Firefox 2 support search suggestions.
</p>
<h2 name="Implementing_suggestion_support_in_the_search_plugin">Implementing suggestion support in the search plugin</h2>
<p>To support search suggestions, a search plugin needs to define an extra <code>&lt;Url&gt;</code> element with its <code>type</code> attribute set to <code>"application/x-suggestions+json"</code>.  (This means that a suggestion-supporting engine plugin will have two <code>&lt;Url&gt;</code> elements, the other one being the main <code>text/html</code> search URL.)
</p><p>For example, the Yahoo search plugin has this <code>&lt;Url&gt;</code> entry:
</p>
<pre>&lt;Url type="application/x-suggestions+json" template="https://ff.search.yahoo.com/gossip?output=fxjson&amp;command={searchTerms}"/&gt;
</pre>
<p>If the user types "fir" into the search bar, then pauses, Firefox inserts "fir" in place of <code>{searchTerms}</code> and queries that URL:
</p>
<pre>&lt;Url type="application/x-suggestions+json" template="https://ff.search.yahoo.com/gossip?output=fxjson&amp;command=fir"/&gt;
</pre>
<p>The results are used to construct the suggestion list box.
</p><p>See <a href="en/Creating_MozSearch_plugins">Creating MozSearch plugins</a> to learn more about how to implement a search plugin.
</p>
<h2 name="Implementing_search_suggestion_support_on_the_server">Implementing search suggestion support on the server</h2>
<p>The majority of the work in handling search suggestions is actually implemented on the server side.  If you're a web site designer, and want to support search suggestions, you need to implement support for returning the suggestions in <a class="external" href="https://www.json.org/">JavaScript Object Notation</a> (JSON) given a search term.
</p><p>When the browser wants to fetch possible matches for a search term, it then sends an HTTP GET request to the URL specified by the <code>&lt;Url&gt;</code> element.
</p><p>Your server should then decide upon the suggestions to offer using whatever means it sees fit, and construct a JSON array that consists of at least two, and as many as four, elements:
</p>
<dl><dt> <b>query string</b>
</dt><dd> The first element in the array is the original query string.  This allows Firefox to verify that the suggestions match the current search term.
</dd></dl>
<dl><dt> <b>completion list</b>
</dt><dd> An array of suggested search terms.  The array should be enclosed in square brackets.  For example: <code>{{mediawiki.external('\"term 1\", \"term 2\", \"term 3\", \"term 4\"')}}</code>
</dd></dl>
<dl><dt> <b>descriptions</b>
</dt><dd> This optional element is an array of descriptions for each of the suggestions in the <i>completion list</i>.  These can be any additional information the search engine might want to return to be displayed by the browser, such as the number of results available for that search.
</dd></dl>
<div class="note">Descriptions are not supported in Firefox 2, and are ignored if any are specified.</div>
<dl><dt> <b>query URLs</b>
</dt><dd> This optional element is an array of alternate URLs for each of the suggestions in the <i>completion list</i>.  For example, if you want to offer a map link instead of just a search result page for a given suggestion, you can return an URL to a map in this array.
</dd></dl>
<dl><dd> If you don't specify a query URL, the default query is used based on the search described by the <code>&lt;Url&gt;</code> element in the search plugin's XML description.
</dd></dl>
<div class="note">Query URLs are not supported in Firefox 2, and are ignored.</div>
<dl><dd> This enhancement - the handling of and forwarding to the query URL if present - is now formally requested in <a class="external" href="https://bugzilla.mozilla.org/show_bug.cgi?id=386591">Bugzilla 386591</a>.
</dd></dl>
<p>For example, if the search term is "fir", and you don't need to return descriptions or alternate query URLs, you might return the following JSON:
</p>
<pre class="eval">["fir", ["firefox", "first choice", "mozilla firefox"]]
</pre>
<p>Note that in this example, only the query string and completion array are specified, leaving out the optional elements.
</p><p>Your completion list can include as many suggestions as you like, although it should be kept manageable, given that the display will be updating live while the user is typing their search string.  In addition, the method you use to select suggestions is entirely up to you.
</p>{{ wiki.languages( { "ca": "ca/Implementaci\u00f3_de_suggeriments_en_els_connectors_de_cerca", "es": "es/Permitir_sugerencias_en_los_plugins_de_b\u00fasqueda", "fr": "fr/Gestion_de_suggestions_dans_les_plugins_de_recherche", "it": "it/Supportare_i_suggerimenti_nei_plugin_di_ricerca", "ja": "ja/Supporting_search_suggestions_in_search_plugins", "pl": "pl/Wsparcie_dla_podpowiedzi_wyszukiwania_w_wyszukiwarkach", "zh-tw": "zh_tw/\u8b93\u641c\u5c0b\u6a21\u7d44\u652f\u63f4\u641c\u5c0b\u5efa\u8b70" } ) }}