Revision 430697 of Supporting search suggestions in search plugins

<p>Firefox supports search suggestions; as the user types in the search bar, Firefox queries the URL specified by the search engine 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>
<h2 id="Implementing_suggestion_support_in_the_search_plugin" 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-US/docs/" title="/en-US/docs/">Creating OpenSearch plugins for Firefox</a> to learn more about how to implement a search plugin.</p>
<h2 id="Implementing_search_suggestion_support_on_the_server" 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 return a JSON array of results:</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, 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, and are ignored.<br />
  This enhancement request - the handling of a selected suggestion, namely calling of a full specified URL as <a class="external" href="https://www.opensearch.org/Specifications/OpenSearch/Extensions/Suggestions/1.0#Query_URLs">proposed in the opensearch standard</a> - is tracked in {{ Bug(386591) }}.</div>
<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>
<div class="note">
  <p><strong>Note</strong>: Firefox requires that suggest requets complete within 500ms for suggestions to be displayed. If the request for the suggest URL does not return data before 500ms have elapsed, no search suggestions will be shown.</p>
</div>
<p>{{ 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" } ) }}</p>