geomap widget

Once you have an HTML element to target, you can call the geographic map widget's function.

.geomap( options )

overview

The widget creates an interactive map. Users can pan and zoom on desktop and mobile browsers against many different cached tile sets or dynamic map servers. Developers can handle events triggered by user action.

options

The options argument is a JavaScript object that configures the map widget during the first instantiation on a div. No options are required. By default the map will show the whole world using the mapquest open tile set.

After initializing a map with your first geomap call, you can get or set most of these options using the following syntax:

// get the current value of a single option
var optionValue = $( map selector ).geomap( "option", optionName );

// set a new value for a single option
$( map selector ).geomap( "option", optionName, newValue );

// set new values for multiple options at the same time
$( map selector ).geomap( "option", {
  optionName: newValue,
  optionName: newValue
} );

Two exceptions are pixelSize (which is read-only) and zoomFactor (which is init-only).

The map view refreshes when you change these options: bbox, center, services, tilingScheme, bboxMax, & zoom.

projection

The geomap widget will match how you use projection with map units. The map unit type (projected or geodetic) you used when you last set the bbox, bboxMax, or the center option will be used as output for options and as values for arguments. If you never set the bbox or center options, the geomap widget will return geodetic coordinates.

For example, if you set the map's center option using geodetic coordinates (a longitude, latitude array), future requests for the value of the map's center or bbox options will be returned in geodetic coordinates. However, if you later set the bbox option using web mercator, future requests for the center or bbox options will be returned in that projection.

Changing bbox or center will affect all options and arguments that use map units. The options and arguments involved are:

• bbox option
• bboxMax option
• center option
• bbox property of the services object's src argument
• GeoJSON objects passed as the geo argument in all events
• return value of the toMap method

To avoid confusion, it is recommended to stick to one map unit type for any single map widget.

The geomap widget will use the $.geo.proj object when needed to convert between geodetic and projected coordinates.

events

All event callbacks receive two arguments: the original browser event and an object specific to the map action.

The map unit type (projected or geodetic) of the map event arguments depends on the way you initialize the map widget. If you have set the center or bbox option using geodetic coordinates, the event arguments will also be in geodetic coordinates.

Like jQuery UI widgets, geomap triggers events directly on the original map div.

Programatic changes to options do not trigger events.

The dblclick event is special in that you can prevent the default action, zoom-in one level, by calling e.preventDefault() in your callback. This is currently the only geomap event that you can prevent the default action. Calling preventDefault in the callback of any other geomap event has undefined results.

There are four geomap event types. The type of event determines what is sent to your event handler as the second argument, geo.

position events

With position events the geo argument to your callback is a GeoJSON Point object having two properties: type & coordinates. The coordinates property is a single GeoJSON position, i.e., an array containing the x/longitude and y/latitude value.

The geo argument to your callback is a true GeoJSON object and you can pass this object directly to the append method. You can also send it directly to a database for storage knowing that there are no non-GeoJSON properties wasting space.

The following events are position events:

Simple modes which trigger position events

The following modes will send a position event when a user clicks on the map without triggering other behavior.

Compound modes which trigger position events

The following modes will send a position event when a user clicks on the map in the midst of performing a larger action, such as on each click while drawing a line.

Each click event while drawing & measuring can be cancelled by calling e.preventDefault() in your click handler. This can be useful if, e.g., a user is drawing a polygon but attempts to add a point that's outside of a designated area, you can cancel that specific point being added to the shape and supply a warning.

bbox events

With bbox events the geo argument to your callback is an object with single property, bbox, which is a GeoJSON bounding box.

shape events

With shape events, the geo argument to your callback is a GeoJSON geometry object having two properties: type & coordinates. The object type will be either Point, LineString or Polygon depending on the current geomap mode: measureLength, measureArea, drawPoint, drawLineString, and drawPolygon.

The geo argument to your callback is a true GeoJSON object and you can pass this object directly to the append method. You can also send it directly to a database for storage knowing that there are no non-GeoJSON properties wasting space.

load events

With load events, the geo argument is currently undefined. You can add the argument to your handler's argument list if you wish but attempting to access any property on it will cause a JavaScript error.

methods

The geomap widget provides some methods to help make interacting map data a little easier.

unit conversion

Convert positions between pixel and map coordinates.

map methods

These methods update the map widget as a whole.

service modification

Methods that help update objects in the services array.

shapes

These methods manage geometry or features drawn on the geomap widget itself or on individual servies within the map.

The find method allows you to search for shapes appended to the map. Its syntax and service-level operation is slightly different than the other three shape methods so the link is visually broken out from the rest.

style

A geomap style is an object whose properties follow a subset of SVG styling properties. The specific styles that geomap recognizes and to which geometry they apply are listed below.

Use the drawStyle option of the geomap widget to define the style used on incomplete lines and polygons as they are being drawn when mode is drawLineString or drawPolygon.

Use the shapeStyle option to define the style of shapes drawn after being appended to the map via the append method.

Please note that in drawPoint mode, the shape event is triggered immediately and so no shape will appear until you append a point to the map at which time the shapeStyle will be used.

geomap style properties

All properties apply to Point shapes which means that you can adjust the stroke and fill of the box surrounding the point location.