append

// a single point, no style, no label, refresh immediately
$(map or service selector).geomap( "append", { type: "Point", coordinates: [ -71, 40 ] } )

// a single line, don't refresh yet
$(map or service selector).geomap( "append", {
  type: "LineString",
  coordinates: [ [ -71, 40 ], [ -71.5, 41 ] ]
}, false )

// a polygon with a style
$(map or service selector).geomap( "append", {
  type: "Polygon",
  coordinates: [ [ 
    [-75, 39.7],
    [-74.8, 39.3],
    [-75.2, 39.3],
    [-75, 39.7]
  ] ]
}, { stroke: "#11117f", strokeWidth: "3px" } )

// an array of geometry objects with a style, don't refresh yet
$(map or service selector).geomap( "append", [ 
  { type: "Point", coordinates: [ -71, 40 ] },
  { type: "Point", coordinates: [ -70, 39.5 ] },
], { color: "green", strokeWidth: "3px" }, false )

// a point feature with a label
$(map or service selector).geomap( "append", {
  type: "Feature",
  geometry: {
    type: "Point",
    coordinates: [ -71, 40 ]
  }
}, "My Point" )

// a point with a label, don't refresh yet
$(map or service selector).geomap( "append", { type: "Point", coordinates: [ -71, 40 ] }, "My Point (don't refresh yet)", false )

// a point with a style & label
$(map or service selector).geomap( "append", { type: "Point", coordinates: [ -71, 40 ] }, { color: "#00f" }, "Blue Point" )

// a collection of features with a style, each point will get a separate label, don't refresh yet
$(map or service selector).geomap( "append", {
    type: "FeatureCollection"
    features: [ {
      type: "Feature",
      geometry: {
        type: "Point",
        coordinates: [ -71, 40 ]
      }
    }, {
      type: "Feature",
      geometry: {
        type: "Point",
        coordinates: [ -71.2, 40.3 ]
      }
    } ]
  },
  { color: "#00f" },
  '<span style="color: #44f;">Blue Point</span>',
  false
)

The append method adds one shape or an array of shapes to the map. In this documentation, the word shape means a GeoJSON geometry object or a GeoJSON Feature. A FeatureCollection is treated as an array of shapes.

When you append more than one shape by using an array or a FeatureCollection, each shape in the array or FeatureCollection's features property is added as a separate shape whereas the other collection geometry types, e.g., MultiPoint, are added as a single shape. This is an important distinction when considering the find method and labels. The find method can potentially return only one shape from an array or one feature of a FeatureCollection but will return all shapes in a MultiPoint (as a reference to the original MultiPoint object supplied to append) even if only one of the coordinates in the MultiPoint intersects the find position. For labeling, each shape in an array and each feature in a FeatureCollection get their own label, however all polygons in a MultiPolygon will share the same label.

The geomap widget maintains a reference to your shape. You can use the same object in calls to remove in order to remove the shape from the map at any time.

The jQuery UI widget factory returns the original jQuery collection to maintain call chaining.

styling

The optional style argument modifies how geomap draws the specific geometry or feature you are adding. Properties supplied in this style will override ones of the same name in geomap's base shapeStyle. Properties not referenced are inheritied from the base style and can change with future changes to the shapeStyle option. Please see the shapeStyle method documentation for information about what properties are valid for this object.

labeling

The optional label argument will display a label near the shape. Labels are a powerful way to add text, pixel-based graphics, or other HTML and CSS effects to the map. The label string can be any text or HTML. For example, consider the following:

• you append a Point shape setting its style to have zero for width and height:

  { width: "0px", height: "0px" }

• you also supply a label of nothing more than a div element with a class:

  '<div class="marker"></div>'

• in a CSS style sheet, you give the marker class a width, height, background image and negative relative position:

  .marker
  {
    width: 8px;
    height: 8px;
    background: url(../img/marker.png);
    position: relative;
    left: -4px;
    top: -4px;
  }

In the above example, marker.png will be centered on every point added with a similar label. The regular shape style will not show because the point style has no size.

For Point shapes, the top-left of the label is positioned at the Point's only coordinate. For LineString shapes, the label is usually positioned 50% along the shape but will be forced into view if its usual position is out of the map's current bbox. For Polygon shapes, the label is usually positioned at the centroid but will be forced into view if its usual position is out of the map's current bbox. All other non-basic shape types use the shape's centroid.

The geomap widget uses a div to position the labels. The div exists inside a container for the service. The div has the CSS class: geo-label. You can use this design to apply regular CSS style to all labels or all labels within a service. The following snippets show examples of using this, assuming the main map div has the id "map" and the default map service (which has the CSS class "osm") has not been changed.

JavaScript

/* add a point to the map itself */
$( "#map" ).geomap( "append", { type: "Point", coordinates: [ -71, 40 ] }, "map point" );

/* add a point to the default map service */
$( "#map .osm" ).geomap( "append", { type: "Point", coordinates: [ -70, 40 ] }, "service point" );

CSS

/* turn the color of all labels blue */
#map .geo-label { color: blue; }

/* make labels on the default basemap service bold */
#map .osm .geo-label { font-weight: bold; }

One caveat is that, to keep performance high, jQuery Geo will not create the .geo-label container if you do not at least pass an empty string as the label. So, if you want to do something similar to the marker example above, but using the already provided .geo-label div, you will need to pass an empty string as the label.

Each .geo-label div is absolutely positioned to the correct location in the map view. Please keep that in mind because changing the position, left or top CSS properties on the .geo-label class may affect your labels drastically.

clickable label links

Shapes appended to the primary map element (as opposed to service-level shapes mentioned below) can have clickable link elements. This means, if you include an "a" element in the label for a shape appended to your map, users can click that link. This also means that the link elements interfere with map interaction, so be careful how your design your labels because they can stop users from panning while hovering over a clickable label link.

Due to browser inconsistencies, sometimes links in service-level shape labels can be clicked. However, since this behavior is not consistent, you should not rely on it.

// users can click the link in this shape's label
$( "#map" ).geomap( "append", { type: "Point", coordinates: [ -71, 40 ] }, "<a href='info.html'>More info</a>" );

// users cannot click the link in this service-level shape's label
$( "#map .osm" ).geomap( "append", { type: "Point", coordinates: [ -71, 40 ] }, "<a href='info.html'>More info</a>" );

Note: If you display non-map content over the map div, links in the shape labels will show through that content unless you give your overlay content a z-index greater than 1.

delaying refresh

The optional refresh argument determines if geomap refreshes the map graphics after this call to append. It defaults to true. If you pass false, geomap will add the shape internally but not immediately redraw the graphics. The changes will display if the user moves the map or you call geomap's refresh method.

service-level shapes

The geomap widget allows you to append a shape to a specific service. You do this by targeting a service inside a map instead of the map itself for your call to geomap's append method. For example, the default map service has the CSS class: osm. We can append a shape to that service specifically by using jQuery to target the service:

$( "#map .osm" ).geomap( "append", shape );

Some of the important advantages with this syntax are:

• you can show or hide shapes as you toggle a service because shapes attached to a service are only visible if the service is visible
• service-level shapes draw in the order of their service in the services option which gives you finer control over how they look
• shapes on the map itself always draw above service-level shapes
• you can style shapes differently depending on their service using a service-level shapeStyle option

duplicate shapes

You can add the same GeoJSON object to more than one service, which allows you to give the same object two different styles at the same time. To do this, call append twice with the same object. Once on one service (or the map itself) and a second time on a different service.

You can also do this at the same time by using the comma selector in one call to append:

// set the basemap service's shapeStyle option to a white halo effect
$( "#map .osm" ).geomap( "option", "shapeStyle", { strokeWidth: "8px", color: "#dedede" } );

// append the shape to both the map widget and basemap service
$( "#map,#map .osm" ).geomap( "append", shape );

updating

If you attempt to add a shape to the map or a service where it already exists, the shape will remain but you will update (or remove) the shape's style or label.

// add the shape with a green color
$( "#map" ).append( shape, { color: "green" } );

// change the color to blue (shape is the same object as before in this case)
$( "#map" ).append( shape, { color: "blue" } );

Changing the type of geometry, e.g., from Point to LineString, or coordinates of a shape you have appended is not recommended and geomap's behavior is currently undefined. If you wish to do either of these, you should first call remove on the original object and append on a new one.