| 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 |
}; |