Destination: Frustration

New in 7.7, WebGUI now has a Map asset. Using a simple point, click, and drag interface, you can build and populate maps with locations. Behind this asset is the Google Maps API, a JavaScript/AJAX interface into Google's maps. However, even as simple as the WebGUI Map asset is no easy feat for the Google Maps API. In fact, this programmer found himself doing some very poor programming practices to get even this much flexibility out of the minimal API provided.

First, Google's Map API is not just for the map. It also provides event listening and AJAX functionality. However, they are far beneath any standard JS library like YUI. They are the bare minimum needed to perform their function, with no special niceties. This itself is not much of a problem, just combine the Google Maps API with your favorite JS library, but it was one more cloud of annoyance in a rainstorm.

Next, when you finally get into the Maps API, you're going to do something wrong that requires debugging. Only you're going get errors like “this.kh has no properties”. Would you know by looking that “kh” is actually the GMarker class's GMarkerOptions object? Does this obfuscation make the JS file much, much smaller? Yes. Does it make it nearly impossible to debug? Yes. Is there a de-obfuscated version for debugging purposes? I sure didn't find one.

Keeping with the GMarkerOptions, there is no way in the API to edit those options once the GMarker is created. So if I want to change the title of a point on the map, I must explicitly change “this.kh.title” to the title that I want. Do I know that “kh” is always going to be what the GMarkerOptions is obfuscated into? When it changes, there will be more “this.kh has no properties” errors. Is the person debugging this going to know why that is happening?

There are other methods missing from a fully-featured Maps API. How do I get the Map object the marker is placed on? Right now, I have to keep track of it myself. Consequently, there's no way for the Marker to tell the map “Hey! Focus on me!” I have to get the marker's lat/long, tell the map to pan, tell the map to zoom if necessary, and then hopefully the info window will open when I tell it to (sometimes the pop-up just doesn't open for some unknown reason).

Finally, the Geocoding API (translate an address like “1600 Pennsylvania Avenue, Washington DC” into latitude / longitude coordinates) returns the lat/long in an array of [ long, lat ]. Who in their right mind would reverse those two, considering every single person learns to read the coordinates in lat, long order? The idea of “self-documenting” APIs is based on “doing what the programmer expects.” Most people expect latitude and longitude to be given in [ lat, long ] order. What is gained by going against this expectation? I'd be less annoyed if this didn't cause about 4 hours of puzzlement.

In addition to the frustrations caused by the Maps API, Firefox decided to do some extremely dumb things: When using an <iframe> to do an AJAXy form submit with a file upload, you cannot send back a mime type of “application/json”, because Firefox will show the user the “Open File” dialog box, even if the “Content-Disposition” header is set to “inline” (meaning show it in the browser, no matter what). This would be no big deal, give it a mime type of text/plain, right? Problem there is Firefox automatically puts a <pre> tag around content with a mime type of text/plain, so when YUI tries to get the content and parse it as JSON, it fails. In the end, I had to send it as “text/html”, a complete misnomer. Again, I'd be less annoyed if this also didn't cause more than 4 hours of puzzlement.

The Google Maps API does what it says it does: It provides you with a map and a way to add points and other features to it. The problem is it does so in a very inconvenient and counter-intuitive way. If you must work with the Maps API, use your own favorite JS library whenever possible. Don't be afraid to subclass the GMaps objects to make something more convenient (I might do this and release the results). And be prepared for some cuts, the Map's got some sharp edges.