We keep some plugin design decisions here.
The geomap widget uses the same widget factory that all other jQuery UI and jQuery Mobile widgets use. Like jQuery Mobile, we include a copy of jquery.ui.widget.js in the project. While this adds 3k to the final compressed build it allows us to easilly follow the patterns designed by UI and better integrate into the jQuery plugin community.
$.widget( "geo.geomap", { } );
The public properties bbox, bboxMax and center do not always match the internal state of the map widget. In fact internally, geomap only tracks center and pixelSize. The bbox and bboxMax properties are calculated based on the current or max center and pixelSize. In the code, you will see two properties each for each of these. One is public, the other is private. For center, the internal position (_center) is always in internal map units (web mercator meters by default) even if the developer sets the public bbox or center by longitude & latitude.
You may notice that we override jQuery UI's _createWidget function in order to capture the options passed in by the user. Let us know if there's a better way to do that. At the end of _create, we iterate over the passed options and set certain internal state values before creating services and refreshing the map. This insures that we handle supplied bbox or center properly. Since bbox and center can potentially conflict, only supply one. If both are supplied the behavior is technically undefined but currently center will override bbox.
When you append a shape to the map, the geomap widget will cache the shape's bounding box (in non-geodetic coordinates) for faster searches when you call find. When you remove a shape from the map, the cache will be cleared. When you use the $.geo.bbox method on a shape after it has been appended to the map, the cached bounding box will be returned.
// the bbox of an appended shape is cached while it is on the map
var calculatedBbox = $.geo.bbox(shape);
$("#map").geomap("append", shape);
var cachedBbox = $.geo.bbox(shape);
$("#map").geomap("remove", shape);
var calculatedAgain = $.geo.bbox(shape);
jQuery Geo caches the bbox using jQuery's data function under the name geoBbox. Though I can't think of a reason to do so, you can remove this cache by calling removeData directly on the shape object:
$.removeData(shape, "geoBbox");
jQuery Geo's caching will not alter your geometry object so you don't have to worry about unintentionally storing or sending extra data to a server.
Apart from the jQuery UI widget factory, geomap includes a couple external libraries.
We've found this to be a very stable mousewheel special event plugin and are using it to handle mouse wheel interaction. This plugin's license comment and source are included intact in the minified releases of jQuery Geo.
We include parts of Google's excanvas library to support graphic drawing in IE6-8. Only functions required to support jQuery Geo's feature list are included. This library's license comment and source are included intact in the non-minified releases of jQuery Geo. The license comment and partial source are included intact in the minified releases of jQuery Geo.
jQuery Geo includes a snapshot of jsRender, the next-generation templating engine from the jQuery team. This is used for measure text templates and src string templates.
Developers can set the services array used by the geomap widget. When it comes time to draw map images, the geomap widget uses an internal _serviceTypes object. The object contains one property for each service type geomap supports, e.g., tiled and shingled. The type property on each service object determines which serviceType object geomap uses to refresh the service. The following code snippet is a simplification of the relationship.
options: {
services: [
{
"class": "osm",
type: "tiled"
/* ,... */
}
]
},
_serviceTypes: {
tiled: {
refresh: function (map, service) {
}
/* ,... */
}
}
In the future the _serviceTypes property will be public and developers can extend the service types geomap supports.