Examine individual changes

[ 0 => '== Notice ==', 1 => '', 2 => '{{Draft notice}}', 3 => '', 4 => '== Introduction ==', 5 => '', 6 => 'The OpenSearch Suggestions extension offers a convention by which search engines can return a set of search term completions for a given search prefix. The search completions can be used by a search client to dynamically present the end user with search term suggestions.', 7 => '', 8 => '== Background ==', 9 => '', 10 => 'The [http://www.google.com/webhp?complete=1&hl=en Google Suggest] project pioneered a mechanism for dynamically presenting a list of search term completions as the user interacts with the search interface. The [http://www.mozilla.com/firefox/ Firefox] web browser was the first to incorporate this technique into the browser search box to offer the user dynamic search term suggestions, a technique subsequently adopted by [http://www.microsoft.com/windows/products/winfamily/ie/default.mspx Internet Explorer], [http://www.apple.com/safari/ Safari], and [http://www.google.com/chrome Chrome]. This document is based on the original [http://wiki.mozilla.org/Search_Service/Suggestions Firefox Search Service design documentation], and subsequently updated for clarity and to include additional search parameters.', 11 => '', 12 => '== Overview ==', 13 => '', 14 => 'The search engine publishes an [[Specifications/OpenSearch/1.1/Draft_3#OpenSearch_description_document|OpenSearch description document]] containing two [[Specifications/OpenSearch/1.1/Draft_3#The_.22Url.22_element|Url elements]]. The first <code>Url</code> element is of type <code>type="application/x-suggestions+json"</code> and indicates to the client how to retrieve a list of suggested searches for a given search prefix. The second <code>Url</code> element is usually of <code>type="text/html"</code> and is used by the search client to perform one of the suggested search queries. Additionally, the second query template may request parameters about the search suggestion that led to the final search query.', 15 => '', 16 => '== Type ==', 17 => '', 18 => 'The following type is used to indicate that the response contains JSON formatted search suggestions:', 19 => '', 20 => ': <code>application/x-suggestions+json</code>', 21 => '', 22 => '== Namespace ==', 23 => '', 24 => 'The XML namespace of the OpenSearch Suggestions Extension is:', 25 => '', 26 => ': <code><nowiki>http://www.opensearch.org/specifications/opensearch/extensions/suggestions/1.1</nowiki></code>', 27 => '', 28 => 'This namespace and a corresponding namespace prefix must be included when the extension is used in an OpenSearch Description document.', 29 => '', 30 => '== OpenSearch description document ==', 31 => '', 32 => 'Search engines that support search suggestions can use the OpenSearch description document to publish URL templates for both retrieving the list of suggestions and for performing follow-up search queries.', 33 => '', 34 => '=== Declaring a JSON-formatted search suggestion URL ===', 35 => '', 36 => 'Search engines should publish a <code>Url</code> element of <code>type="application/x-suggestions+json"</code> to indicate that they can be queried for a list of search suggestions in JSON format.', 37 => '', 38 => '==== Example ====', 39 => '', 40 => 'Example of publishing the location of a JSON-formatted search suggestion query:', 41 => '', 42 => ' <?xml version="1.0" encoding="UTF-8"?>', 43 => ' <OpenSearchDescription xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>">', 44 => ' '''<Url type="application/x-suggestions+json"'''', 45 => ' '''template="<nowiki>http://example.com/suggest?q={searchTerms}</nowiki>"/>'''', 46 => ' <nowiki><!-- ... --></nowiki>', 47 => ' </OpenSearchDescription>', 48 => '', 49 => '=== Declaring a URL for follow-up search queries ===', 50 => '', 51 => 'After the list of search suggestions has been retrieved, the client will likely perform a full follow up search, as is documented using a standard [[Specifications/OpenSearch/1.1/Draft_3#The_.22Url.22_element|Url element]], usually of <code>type="text/html"</code>, in the OpenSearch description document. In addition to the usual query template parameters, this specification introduces the <code>suggestionPrefix</code> and the <code>suggestionIndex</code> extension parameters to provide additional context to the search engine.', 52 => '', 53 => 'The extension parameters are in the <code><nowiki>http://www.opensearch.org/specifications/opensearch/extensions/suggestions/1.1</nowiki></code> namespace, which must be explicitly declared as a [[Specifications/OpenSearch/1.1/Draft_3#Fully_qualified_parameter_names|fully qualified parameter name]] using an <code>xmlns</code> declaration.', 54 => '', 55 => 'These extension parameters could be used in any Url template, but the meaning is defined here only when they are used in the context of a follow-up search query generated from a list of suggested searches.', 56 => '', 57 => '==== The "suggestionPrefix" parameter ====', 58 => '', 59 => 'When the search query was generated as a result of a search suggestion, the <code>suggestionPrefix</code> variable is replaced by the string used to generate the search suggestion.', 60 => '', 61 => 'Note the search server should use the "<code>?</code>" flag in the URL template when requesting the <code>suggestionPrefix</code> parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the suggestions extension.', 62 => '', 63 => '==== The "suggestionIndex" parameter ====', 64 => '', 65 => 'When the search query was generated as a result of a search suggestion, the <code>suggestionIndex</code> variable is replaced by the location of the selected suggestion within the list, offset from 0.', 66 => '', 67 => 'Note the search server should use the "<code>?</code>" flag in the URL template when requesting the <code>suggestionIndex</code> parameter to indicate that this parameter is optional and that a search can still be performed even if the client does not recognize the suggestions extension.', 68 => '', 69 => '==== Example ====', 70 => '', 71 => 'Example of a Url template that accepts additional information when used in conjunction with suggested searches:', 72 => '', 73 => ' <?xml version="1.0" encoding="UTF-8"?>', 74 => ' <OpenSearchDescription ', 75 => ' xmlns="<nowiki>http://a9.com/-/spec/opensearch/1.1/</nowiki>"', 76 => ' '''xmlns:suggestions="<nowiki>http://www.opensearch.org/specifications/opensearch/extensions/suggestions/1.1"</nowiki>'''>', 77 => ' <Url type="text/html"', 78 => ' template="<nowiki>http://example.com?q={searchTerms}</nowiki>', 79 => ' &amp;amp;'''prefix={suggestions:suggestionPrefix?}'''', 80 => ' &amp;amp;'''index={suggestions:suggestionIndex?}"'''/>', 81 => ' <nowiki><!-- ... --></nowiki>', 82 => ' </OpenSearchDescription>', 83 => '', 84 => '== JSON-formatted search suggestion responses ==', 85 => '', 86 => '=== Response format ===', 87 => '', 88 => 'The response body should be returned in [http://www.json.org/ JavaScript Object Notation] as a JavaScript array of arrays.', 89 => '', 90 => '=== Response content ===', 91 => '', 92 => 'Search suggestions are returned as an ordered collection of values. ', 93 => 'The four values are returned in the following order:', 94 => '', 95 => '* Query String', 96 => '* Completions', 97 => '* Descriptions', 98 => '* Query URLs', 99 => '', 100 => '==== Suggestion prefix ====', 101 => '', 102 => 'Description: A single element echoing the requested search term. The search client may validate that this value matches the expected response.', 103 => '', 104 => 'Required: yes', 105 => '', 106 => 'Example:', 107 => '', 108 => ' "sea"', 109 => '', 110 => '==== Search terms ====', 111 => '', 112 => 'Description: A list of suggested completions for the given search term. These can be used as the value for the <code>searchTerms</code> parameter of a subsequent search.', 113 => '', 114 => 'Required: yes', 115 => '', 116 => 'Example:', 117 => '', 118 => ' ["sears",', 119 => ' "search engines",', 120 => ' "search engine",', 121 => ' "search",', 122 => ' "sears.com",', 123 => ' "seattle times"]', 124 => '', 125 => '==== Descriptions ====', 126 => '', 127 => 'Description: A list of human-readable strings that provide additional information or context regarding the suggested completion. ', 128 => '', 129 => 'Required: no', 130 => '', 131 => 'Example:', 132 => '', 133 => ' ["7,390,000 results",', 134 => ' "17,900,000 results",', 135 => ' "25,700,000 results",', 136 => ' "1,220,000,000 results",', 137 => ' "1 result",', 138 => ' "17,600,000 results"]', 139 => '', 140 => '==== Query URLs ====', 141 => '', 142 => 'Description: A list of URLs that should be used by the search client to request the suggested search term at the corresponding position in the completions lists.', 143 => '', 144 => 'Required: no', 145 => '', 146 => 'Example:', 147 => '', 148 => ' [<nowiki>"http://example.com?q=sears",', 149 => ' "http://example.com?q=search+engines",', 150 => ' "http://example.com?q=search+engine",', 151 => ' "http://example.com?q=search",', 152 => ' "http://example.com?q=sears.com",', 153 => ' "http://example.com?q=seattle+times"</nowiki>]', 154 => '', 155 => '=== Example ===', 156 => '', 157 => 'The following is a full example of a JSON formatted search suggestions response:', 158 => ' ', 159 => ' ["sea",', 160 => ' ["sears",', 161 => ' "search engines",', 162 => ' "search engine",', 163 => ' "search",', 164 => ' "sears.com",', 165 => ' "seattle times"],', 166 => ' ["7,390,000 results",', 167 => ' "17,900,000 results",', 168 => ' "25,700,000 results",', 169 => ' "1,220,000,000 results",', 170 => ' "1 result",', 171 => ' "17,600,000 results"],', 172 => ' [<nowiki>"http://example.com?q=sears"</nowiki>,', 173 => ' <nowiki>"http://example.com?q=search+engines"</nowiki>,', 174 => ' <nowiki>"http://example.com?q=search+engine"</nowiki>,', 175 => ' <nowiki>"http://example.com?q=search"</nowiki>,', 176 => ' <nowiki>"http://example.com?q=sears.com"</nowiki>,', 177 => ' <nowiki>"http://example.com?q=seattle+times"</nowiki>]]', 178 => '', 179 => '', 180 => '== License ==', 181 => '', 182 => 'This document is made available by [http://a9.com A9.com] subject to the terms of the [http://creativecommons.org/licenses/by-sa/2.5/ Creative Commons Attribution-ShareAlike 2.5 License].', 183 => '', 184 => '[[Category:Specification]]', 185 => '[[Category:Extension]]' ]