Debian Codegraph @

closure-library/closure/goog/ui/ac/remotearraymatcher.js

raw
1 // Copyright 2007 The Closure Library Authors. All Rights Reserved.
2 //
3 // Licensed under the Apache License, Version 2.0 (the "License");
4 // you may not use this file except in compliance with the License.
5 // You may obtain a copy of the License at
6 //
7 // http://www.apache.org/licenses/LICENSE-2.0
8 //
9 // Unless required by applicable law or agreed to in writing, software
10 // distributed under the License is distributed on an "AS-IS" BASIS,
11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 // See the License for the specific language governing permissions and
13 // limitations under the License.
14
15 /**
16 * @fileoverview Class that retrieves autocomplete matches via an ajax call.
17 *
18 */
19
20 goog.provide('goog.ui.ac.RemoteArrayMatcher');
21
22 goog.require('goog.Disposable');
23 goog.require('goog.Uri');
24 goog.require('goog.events');
25 goog.require('goog.net.EventType');
26 goog.require('goog.net.XhrIo');
27
28
29
30 /**
31 * An array matcher that requests matches via ajax.
32 * @param {string} url The Uri which generates the auto complete matches. The
33 * search term is passed to the server as the 'token' query param.
34 * @param {boolean=} opt_noSimilar If true, request that the server does not do
35 * similarity matches for the input token against the dictionary.
36 * The value is sent to the server as the 'use_similar' query param which is
37 * either "1" (opt_noSimilar==false) or "0" (opt_noSimilar==true).
38 * @param {goog.net.XmlHttpFactory=} opt_xmlHttpFactory Specify the
39 * XmlHttpFactory used to retrieve the matches.
40 * @constructor
41 * @extends {goog.Disposable}
42 */
43 goog.ui.ac.RemoteArrayMatcher = function(
44 url, opt_noSimilar, opt_xmlHttpFactory) {
45 goog.Disposable.call(this);
46
47 /**
48 * The base URL for the ajax call. The token and max_matches are added as
49 * query params.
50 * @type {string}
51 * @private
52 */
53 this.url_ = url;
54
55 /**
56 * Whether similar matches should be found as well. This is sent as a hint
57 * to the server only.
58 * @type {boolean}
59 * @private
60 */
61 this.useSimilar_ = !opt_noSimilar;
62
63 /**
64 * The XhrIo object used for making remote requests. When a new request
65 * is made, the current one is aborted and the new one sent.
66 * @type {goog.net.XhrIo}
67 * @private
68 */
69 this.xhr_ = new goog.net.XhrIo(opt_xmlHttpFactory);
70 };
71 goog.inherits(goog.ui.ac.RemoteArrayMatcher, goog.Disposable);
72
73
74 /**
75 * The HTTP send method (GET, POST) to use when making the ajax call.
76 * @type {string}
77 * @private
78 */
79 goog.ui.ac.RemoteArrayMatcher.prototype.method_ = 'GET';
80
81
82 /**
83 * Data to submit during a POST.
84 * @type {string|undefined}
85 * @private
86 */
87 goog.ui.ac.RemoteArrayMatcher.prototype.content_ = undefined;
88
89
90 /**
91 * Headers to send with every HTTP request.
92 * @type {Object|goog.structs.Map}
93 * @private
94 */
95 goog.ui.ac.RemoteArrayMatcher.prototype.headers_ = null;
96
97
98 /**
99 * Key to the listener on XHR. Used to clear previous listeners.
100 * @type {goog.events.Key}
101 * @private
102 */
103 goog.ui.ac.RemoteArrayMatcher.prototype.lastListenerKey_ = null;
104
105
106 /**
107 * Set the send method ("GET", "POST").
108 * @param {string} method The send method; default: GET.
109 */
110 goog.ui.ac.RemoteArrayMatcher.prototype.setMethod = function(method) {
111 this.method_ = method;
112 };
113
114
115 /**
116 * Set the post data.
117 * @param {string} content Post data.
118 */
119 goog.ui.ac.RemoteArrayMatcher.prototype.setContent = function(content) {
120 this.content_ = content;
121 };
122
123
124 /**
125 * Set the HTTP headers.
126 * @param {Object|goog.structs.Map} headers Map of headers to add to the
127 * request.
128 */
129 goog.ui.ac.RemoteArrayMatcher.prototype.setHeaders = function(headers) {
130 this.headers_ = headers;
131 };
132
133
134 /**
135 * Set the timeout interval.
136 * @param {number} interval Number of milliseconds after which an
137 * incomplete request will be aborted; 0 means no timeout is set.
138 */
139 goog.ui.ac.RemoteArrayMatcher.prototype.setTimeoutInterval = function(
140 interval) {
141 this.xhr_.setTimeoutInterval(interval);
142 };
143
144
145 /**
146 * Builds a complete GET-style URL, given the base URI and autocomplete related
147 * parameter values.
148 * <b>Override this to build any customized lookup URLs.</b>
149 * <b>Can be used to change request method and any post content as well.</b>
150 * @param {string} uri The base URI of the request target.
151 * @param {string} token Current token in autocomplete.
152 * @param {number} maxMatches Maximum number of matches required.
153 * @param {boolean} useSimilar A hint to the server.
154 * @param {string=} opt_fullString Complete text in the input element.
155 * @return {?string} The complete url. Return null if no request should be sent.
156 * @protected
157 */
158 goog.ui.ac.RemoteArrayMatcher.prototype.buildUrl = function(
159 uri, token, maxMatches, useSimilar, opt_fullString) {
160 var url = new goog.Uri(uri);
161 url.setParameterValue('token', token);
162 url.setParameterValue('max_matches', String(maxMatches));
163 url.setParameterValue('use_similar', String(Number(useSimilar)));
164 return url.toString();
165 };
166
167
168 /**
169 * Returns whether the suggestions should be updated?
170 * <b>Override this to prevent updates eg - when token is empty.</b>
171 * @param {string} uri The base URI of the request target.
172 * @param {string} token Current token in autocomplete.
173 * @param {number} maxMatches Maximum number of matches required.
174 * @param {boolean} useSimilar A hint to the server.
175 * @param {string=} opt_fullString Complete text in the input element.
176 * @return {boolean} Whether new matches be requested.
177 * @protected
178 */
179 goog.ui.ac.RemoteArrayMatcher.prototype.shouldRequestMatches = function(
180 uri, token, maxMatches, useSimilar, opt_fullString) {
181 return true;
182 };
183
184
185 /**
186 * Parses and retrieves the array of suggestions from XHR response.
187 * <b>Override this if the response is not a simple JSON array.</b>
188 * @param {string} responseText The XHR response text.
189 * @return {Array<string>} The array of suggestions.
190 * @protected
191 */
192 goog.ui.ac.RemoteArrayMatcher.prototype.parseResponseText = function(
193 responseText) {
194
195 var matches = [];
196 // If there is no response text, JSON.parse will throw a syntax error.
197 if (responseText) {
198
199 try {
200 matches = JSON.parse(responseText);
201 } catch (exception) {
202 }
203 }
204 return /** @type {Array<string>} */ (matches);
205 };
206
207
208 /**
209 * Handles the XHR response.
210 * @param {string} token The XHR autocomplete token.
211 * @param {Function} matchHandler The AutoComplete match handler.
212 * @param {goog.events.Event} event The XHR success event.
213 */
214 goog.ui.ac.RemoteArrayMatcher.prototype.xhrCallback = function(
215 token, matchHandler, event) {
216 var text = event.target.getResponseText();
217 matchHandler(token, this.parseResponseText(text));
218 };
219
220
221 /**
222 * Retrieve a set of matching rows from the server via ajax.
223 * @param {string} token The text that should be matched; passed to the server
224 * as the 'token' query param.
225 * @param {number} maxMatches The maximum number of matches requested from the
226 * server; passed as the 'max_matches' query param. The server is
227 * responsible for limiting the number of matches that are returned.
228 * @param {Function} matchHandler Callback to execute on the result after
229 * matching.
230 * @param {string=} opt_fullString The full string from the input box.
231 */
232 goog.ui.ac.RemoteArrayMatcher.prototype.requestMatchingRows = function(
233 token, maxMatches, matchHandler, opt_fullString) {
234
235 if (!this.shouldRequestMatches(
236 this.url_, token, maxMatches, this.useSimilar_, opt_fullString)) {
237 return;
238 }
239 // Set the query params on the URL.
240 var url = this.buildUrl(
241 this.url_, token, maxMatches, this.useSimilar_, opt_fullString);
242 if (!url) {
243 // Do nothing if there is no URL.
244 return;
245 }
246
247 // The callback evals the server response and calls the match handler on
248 // the array of matches.
249 var callback = goog.bind(this.xhrCallback, this, token, matchHandler);
250
251 // Abort the current request and issue the new one; prevent requests from
252 // being queued up by the browser with a slow server
253 if (this.xhr_.isActive()) {
254 this.xhr_.abort();
255 }
256 // This ensures if previous XHR is aborted or ends with error, the
257 // corresponding success-callbacks are cleared.
258 if (this.lastListenerKey_) {
259 goog.events.unlistenByKey(this.lastListenerKey_);
260 }
261 // Listen once ensures successful callback gets cleared by itself.
262 this.lastListenerKey_ =
263 goog.events.listenOnce(this.xhr_, goog.net.EventType.SUCCESS, callback);
264 this.xhr_.send(url, this.method_, this.content_, this.headers_);
265 };
266
267
268 /** @override */
269 goog.ui.ac.RemoteArrayMatcher.prototype.disposeInternal = function() {
270 this.xhr_.dispose();
271 goog.ui.ac.RemoteArrayMatcher.superClass_.disposeInternal.call(this);
272 };