Wednesday, 7 September 2016

MapGuide tidbits: Turning selection XML into attributes or selection images via the mapagent

Since MapGuide Open Source 2.6, the mapagent has an improved QUERYMAPFEATURES, which allows for greater flexibility to handle the selection and tooltip requirements of our various client-side map viewers. Previously, you would've needed custom server-side code using the MapGuide Web API to achieve this, but now that it is part of the mapagent, all you need is a basic AJAX request.

The main purpose of this operation is to produce an encoded feature selection based on an input geometry (from a mouse click or a box drag) or depending on what you ask for, it can also include:

  • An inline base64 selection image (to avoid a subsequent selection image rendering request)
  • Tooltip/Hyperlink information
  • Attributes and bounding boxes of the selected features
Now what some of you may not know is that you can also use QUERYMAPFEATURES to pass in existing selection XML to get back the inline selection / tooltip / hyperlink / attributes. To do this, you have to omit the GEOMETRY parameter (which normally has the input WKT geometry from the mouse click or box drag) and specify a FEATUREFILTER parameter instead which contains your selection XML. Yes, it's a confusing name. You would've thought it would be named SELECTIONXML or something like that wouldn't you?

Now there is one important note about using QUERYMAPFEATURES in this manner, and was something that I originally thought was a critical bug, but is actually a false positive (hence my motivation for this post): Make sure to include a LAYERATTRIBUTEFILTER with a value of 0.

The LAYERATTRIBUTEFILTER parameter is a bitmask that applies layer-based restrictions on what part of the selection to render:
  • 1 = Include visible layers
  • 2 = Include selectable layers
  • 4 = Include layers with tooltips defined
When the LAYERATTRIBUTEFILTER is not specified, MapGuide will internally default to the value of 3 (include visible and selectable layers). When you combine this with passing up selection XML instead of an input geometry, can you see why it may raise a false alarm? Because your selection XML may be for selected features that are not visible in your current view, so when you pass the selection XML up to QUERYMAPFEATURES without setting LAYERATTRIBUTEFILTER=0, MapGuide will use default visibility/selectability criteria and most likely omit your selected features from the selection image / tooltip / hyperlink / attributes and as a result, you may get back nothing despite passing up valid selection XML and asking for selection image / tooltip / hyperlink / attributes.

So if in doubt, if you're passing up selection XML to QUERYMAPFEATURES, be sure to pass up LAYERATTRIBUTEFILTER=0 as well to avoid any nasty surprises.

No comments: