1 /* Copyright (c) 2006-2008 MetaCarta, Inc., published under the Clear BSD
2 * license. See http://svn.openlayers.org/trunk/openlayers/license.txt for the
3 * full text of the license. */
7 * @requires OpenLayers/Control.js
8 * @requires OpenLayers/Handler/Click.js
9 * @requires OpenLayers/Handler/Hover.js
10 * @requires OpenLayers/Request.js
14 * Class: OpenLayers.Control.WMSGetFeatureInfo
15 * The WMSGetFeatureInfo control uses a WMS query to get information about a point on the map. The
16 * information may be in a display-friendly format such as HTML, or a machine-friendly format such
17 * as GML, depending on the server's capabilities and the client's configuration. This control
18 * handles click or hover events, attempts to parse the results using an OpenLayers.Format, and
19 * fires a 'getfeatureinfo' event with the click position, the raw body of the response, and an
20 * array of features if it successfully read the response.
23 * - <OpenLayers.Control>
25 OpenLayers.Control.WMSGetFeatureInfo = OpenLayers.Class(OpenLayers.Control, {
29 * {Boolean} Send GetFeatureInfo requests when mouse stops moving.
35 * APIProperty: maxFeatures
36 * {Integer} Maximum number of features to return from a WMS query. This
37 * sets the feature_count parameter on WMS GetFeatureInfo
44 * {Array(<OpenLayers.Layer.WMS>)} The layers to query for feature info.
45 * If omitted, all map WMS layers with a url that matches this <url> or
46 * <layerUrl> will be considered.
51 * Property: queryVisible
52 * {Boolean} If true, filter out hidden layers when searching the map for
53 * layers to query. Default is false.
59 * {String} The URL of the WMS service to use. If not provided, the url
60 * of the first eligible layer will be used.
66 * {Array(String)} Optional list of urls for layers that should be queried.
67 * This can be used when the layer url differs from the url used for
68 * making GetFeatureInfo requests (in the case of a layer using cached
74 * Property: infoFormat
75 * {String} The mimetype to request from the server
77 infoFormat: 'text/html',
80 * Property: vendorParams
81 * {Object} Additional parameters that will be added to the request, for
82 * WMS implementations that support them. This could e.g. look like
93 * {<OpenLayers.Format>} A format for parsing GetFeatureInfo responses.
94 * Default is <OpenLayers.Format.WMSGetFeatureInfo>.
99 * Property: formatOptions
100 * {Object} Optional properties to set on the format (if one is not provided
101 * in the <format> property.
106 * APIProperty: handlerOptions
107 * {Object} Additional options for the handlers used by this control, e.g.
110 * "click": {delay: 100},
111 * "hover": {delay: 300}
115 handlerOptions: null,
119 * {Object} Reference to the <OpenLayers.Handler> for this control
124 * Property: hoverRequest
125 * {<OpenLayers.Request>} contains the currently running hover request
131 * Constant: EVENT_TYPES
133 * Supported event types (in addition to those from <OpenLayers.Control>):
134 * getfeatureinfo - Triggered when a GetFeatureInfo response is received.
135 * The event object has a *text* property with the body of the
136 * response (String), a *features* property with an array of the
137 * parsed features, an *xy* property with the position of the mouse
138 * click or hover event that triggered the request, and a *request*
139 * property with the request itself.
141 EVENT_TYPES: ["getfeatureinfo"],
144 * Constructor: <OpenLayers.Control.WMSGetFeatureInfo>
149 initialize: function(options) {
150 // concatenate events specific to vector with those from the base
152 OpenLayers.Control.WMSGetFeatureInfo.prototype.EVENT_TYPES.concat(
153 OpenLayers.Control.prototype.EVENT_TYPES
156 options = options || {};
157 options.handlerOptions = options.handlerOptions || {};
159 OpenLayers.Control.prototype.initialize.apply(this, [options]);
162 this.format = new OpenLayers.Format.WMSGetFeatureInfo(
163 options.formatOptions
168 this.handler = new OpenLayers.Handler.Hover(
170 'move': this.cancelHover,
171 'pause': this.getInfoForHover
173 OpenLayers.Util.extend(this.handlerOptions.hover || {}, {
177 this.handler = new OpenLayers.Handler.Click(this,
178 {click: this.getInfoForClick}, this.handlerOptions.click || {});
184 * Activates the control.
187 * {Boolean} The control was effectively activated.
189 activate: function () {
191 this.handler.activate();
193 return OpenLayers.Control.prototype.activate.apply(
200 * Deactivates the control.
203 * {Boolean} The control was effectively deactivated.
205 deactivate: function () {
206 return OpenLayers.Control.prototype.deactivate.apply(
212 * Method: getInfoForClick
216 * evt - {<OpenLayers.Event>}
218 getInfoForClick: function(evt) {
219 // Set the cursor to "wait" to tell the user we're working on their
221 OpenLayers.Element.addClass(this.map.viewPortDiv, "olCursorWait");
222 this.request(evt.xy, {});
226 * Method: getInfoForHover
227 * Pause callback for the hover handler
232 getInfoForHover: function(evt) {
233 this.request(evt.xy, {hover: true});
237 * Method: cancelHover
238 * Cancel callback for the hover handler
240 cancelHover: function() {
241 if (this.hoverRequest) {
242 this.hoverRequest.abort();
243 this.hoverRequest = null;
249 * Internal method to get the layers, independent of whether we are
250 * inspecting the map or using a client-provided array
252 findLayers: function() {
256 var candidates = this.layers || this.map.layers;
258 for(var i=0, len=candidates.length; i<len; ++i) {
259 layer = candidates[i];
260 if(layer instanceof OpenLayers.Layer.WMS &&
261 (!this.queryVisible || layer.getVisibility())) {
262 url = layer.url instanceof Array ? layer.url[0] : layer.url;
263 // if the control was not configured with a url, set it
264 // to the first layer url
268 if(this.urlMatches(url)) {
279 * Test to see if the provided url matches either the control <url> or one
280 * of the <layerUrls>.
283 * url - {String} The url to test.
286 * {Boolean} The provided url matches the control <url> or one of the
289 urlMatches: function(url) {
290 var matches = OpenLayers.Util.isEquivalentUrl(this.url, url);
291 if(!matches && this.layerUrls) {
292 for(var i=0, len=this.layerUrls.length; i<len; ++i) {
293 if(OpenLayers.Util.isEquivalentUrl(this.layerUrls[i], url)) {
304 * Sends a GetFeatureInfo request to the WMS
307 * clickPosition - {<OpenLayers.Pixel>} The position on the map where the
308 * mouse event occurred.
309 * options - {Object} additional options for this method.
312 * - *hover* {Boolean} true if we do the request for the hover handler
314 request: function(clickPosition, options) {
315 options = options || {};
319 var layers = this.findLayers();
320 if(layers.length > 0) {
322 for (var i = 0, len = layers.length; i < len; i++) {
323 layerNames = layerNames.concat(layers[i].params.LAYERS);
324 // in the event of a WMS layer bundling multiple layers but not
325 // specifying styles,we need the same number of commas to specify
326 // the default style for each of the layers. We can't just leave it
327 // blank as we may be including other layers that do specify styles.
328 if (layers[i].params.STYLES) {
329 styleNames = styleNames.concat(layers[i].params.STYLES);
331 if (layers[i].params.LAYERS instanceof Array) {
332 styleNames = styleNames.concat(new Array(layers[i].params.LAYERS.length));
333 } else { // Assume it's a String
334 styleNames = styleNames.concat(layers[i].params.LAYERS.replace(/[^,]/g, ""));
341 params: OpenLayers.Util.applyDefaults({
344 request: "GetFeatureInfo",
346 query_layers: layerNames,
348 bbox: this.map.getExtent().toBBOX(),
349 srs: this.map.getProjection(),
350 feature_count: this.maxFeatures,
353 height: this.map.getSize().h,
354 width: this.map.getSize().w,
355 info_format: this.infoFormat
356 }, this.vendorParams),
357 callback: function(request) {
358 this.handleResponse(clickPosition, request);
363 var response = OpenLayers.Request.GET(wmsOptions);
365 if (options.hover === true) {
366 this.hoverRequest = response.priv;
370 OpenLayers.Element.removeClass(this.map.viewPortDiv, "olCursorWait");
375 * Method: handleResponse
376 * Handler for the GetFeatureInfo response.
379 * xy - {<OpenLayers.Pixel>} The position on the map where the
380 * mouse event occurred.
381 * request - {XMLHttpRequest} The request object.
383 handleResponse: function(xy, request) {
385 var doc = request.responseXML;
386 if(!doc || !doc.documentElement) {
387 doc = request.responseText;
389 var features = this.format.read(doc);
391 this.events.triggerEvent("getfeatureinfo", {
392 text: request.responseText,
399 OpenLayers.Element.removeClass(this.map.viewPortDiv, "olCursorWait");
404 * Set the map property for the control.
407 * map - {<OpenLayers.Map>}
409 setMap: function(map) {
410 this.handler.setMap(map);
411 OpenLayers.Control.prototype.setMap.apply(this, arguments);
414 CLASS_NAME: "OpenLayers.Control.WMSGetFeatureInfo"