services

[ {
  "class": "osm",
  type: "tiled",
  src: function( view ) {
    return "http://otile" + ((view.index % 4) + 1) + ".mqcdn.com/tiles/1.0.0/osm/" + view.zoom + "/" + view.tile.column + "/" + view.tile.row + ".png";
  },
  attr: "<p>Tiles Courtesy of <a href='http://www.mapquest.com/' target='_blank'>MapQuest</a> <img src='http://developer.mapquest.com/content/osm/mq_logo.png'></p>"
} ] );

$( selector ).geomap( { services: [ {
  "class": "osm",
  type: "tiled",
  src: function( view ) {
    return "http://tile.openstreetmap.org/" + view.zoom + "/" + view.tile.column + "/" + view.tile.row + ".png";
  },
  attr: "© OpenStreetMap & contributors, CC-BY-SA",
  style: {
    visibility: "visible",
    opacity: 1.0
  }
} ] } );

var services = $( selector ).geomap( "option", "services" );

$( selector ).geomap( "option", "services", [ {
  id: "openstreetmap",
  type: "tiled",
  src: function( view ) {
    return "http://tile.openstreetmap.org/" + view.zoom + "/" + view.tile.column + "/" + view.tile.row + ".png";
  },
  attr: "© OpenStreetMap & contributors, CC-BY-SA"
} ]

The services option is an array of service objects. The service objects are JavaScript objects that control how the geomap widget displays map images.

service object

A service object has six properties, two of which are required. The id and class properties are optional but at least one is recommended so you can target specific services with the toggle and opacity methods.

id

Each service can have an id that distinguishes it from other service objects in the array. The id is a string and must be follow the HTML element id naming conditions. If present, the id must be unique across all services in all maps as well as unique from any other HTML element on the page. The default service object of a geomap widget does not have an id.

class

Each service can have a class as well. The class is a string and must be follow the CSS class naming conditions. You can consider this as the class of images the service will supply and usually name it after the service, such as osm, mass-gis, etc. The default service object of a geomap widget has the class: osm.

All services also get the class geo-service whether you supply a class to the service object or not. Therefore, the default service is both .osm (as part of its service object) and .geo-service (as added by the widget).

Unfortunately, class is a reserved word in JavaScript. When you specify class in your service object, you must quote the word class. This is exactly how it's done in jQuery itself when applying attributes to an element based on an object. To quote the jQuery API:

The name "class" must be quoted since it is a JavaScript reserved word, and "className" cannot be used since it is not the correct attribute name.

type

A service object has a type property which is either "tiled" or "shingled". Tiled servies will get one image request per tile needed to fill a given view when the map refreshes. The tile request's bbox will only be the size of the given tile. Shingled services will get only one image request each time the map refreshes and the bbox will be the extent of the whole map view.

src

The src property of a service object can be one of the following three options:

• a function that accepts an object specifying information about the current image request which returns a URL to an image or null to indicate that no image is available or required
• a function that accepts an object specifying information about the current image request which returns a jQuery Promise object and, later, calls either resolve passing a URL to an image or reject to indicate that no image is available
• a template string that the geomap widget can use to build a URL itself

For tiled services, the image is placed at the tile location specified. For shingled services, the image will fill the whole map view.

If the browser's request of the image results in a 404 status the map will not show that tile or image.

When src is a function, the argument to that function has the following properties:

You can use the properties of this argument to build and return a URL (or initiate an AJAX request and return a Promise).

For more infomration about returning a jQuery Promise, please read the section on Deferred Objects in the jQuery API documentation. It might useful to know that, as of jQuery 1.5, the $.ajax method returns a Promise object. If your ajax call returns a URL to an image, your src function can look something like this:

src: function ( view ) { return $.ajax( { ... } ); }

When src is a string, those same properties can be used in the template by surrounding each property with: {{:propertyName}}.

The default value for src is a function because it is slightly faster than rendering a template and we have better control of the view.index property. However, as an example, we can rewrite the default src function as a template string:

Note: Alpha releases used a {{= }} syntax but there is a breaking change in the beta version due to changes in jsRender. Please use the new {{: }} syntax.

src: "http://otile1.mqcdn.com/tiles/1.0.0/osm/{{:zoom}}/{{:tile.column}}/{{:tile.row}}.png"

A couple advantages of using a string are that it is more concise and, unlike a function, can be stored as JSON.

You do not have to have template parameters in the string, so if you want a static map image, you can set src to a static URL.

attr

The attr property is optional. It stands for attribution and is a way to give credit to the source of your map imagery. It defaults to an empty string if not specified in a service object. When present, the map widget displays the HTML provided on the bottom-left corner of the map when the service is visible. Users can click links but cannot interact with all other text or images.

Note: If you display non-map content over the map div, links in the attribution will show through that content unless you either remove anchor elements from your service's attr property or give your overlay content a z-index greater than 1.

style

The style property is optional. It contains presentation options for the service.

The visibility property defaults to "visible". It determines whether or not the map will show images from this service while refreshing. You can change the visibility of a service either by changing the visibility property of the service object to "visible" or "hidden" and then setting geomap's services option or by using the toggle method of the geomap widget. The latter is recommended because it is a lot faster and does not cause services to be recreated.

The opacity defaults to 1.0. It determines how transparent a service is when it is visible. Valid values are floating point numbers between 0 and 1 inclusive. Services with an opacity of 0 will not show on the map even if visible is true. You can change the opacity of a service either by changing the opacity property of the service object and then setting geomap's services option or by using the opacity method of the geomap widget. The latter is recommended because it is a lot faster and does not cause services to be recreated.

modifying services

By default, the geomap widget starts with one service object in the services array. The default service object will display OpenStreetMap data via mapquest open tiles. Setting the services option will replace all existing services with a new set that you specify. You can set a specific part of of a specific service by getting the current array, modifying, adding, or deleting one of the service objects and then re-setting the services option with the modified array.

Note: It is always better to set the services option once, during init, rather than adding or modifying services after the map has been created. Some of the following samples show that it is possible to modify the services option after map initialization through the services option even though it's not recommended.

// create a map
var map = $( "#map" ).geomap( );

// get the current services array
var services = map.geomap( "option", "services" );

// add a service
services.push( {
  id: "Ortho_MapQuest",
  type: "tiled",
  src: function (view) {
    return "http://oatile" + ((view.index % 4) + 1) + ".mqcdn.com/naip/" + view.zoom + "/" + view.tile.column + "/" + view.tile.row + ".png";
  },
  attr: "<p>Tiles Courtesy of <a href='http://www.mapquest.com/' target='_blank'>MapQuest<a> <img src='http://developer.mapquest.com/content/osm/mq_logo.png'><p>"
} );

// hide the first service in the services array
services[ 0 ].style.visibility = "hidden";

// re-set the services option
map.geomap( "option", "services", services );

The following code is more efficient than the last sample:

// build an array of service objects ahead of time
var services = [ {
  id: "OSM",
  type: "tiled",
  src: "http://tile.openstreetmap.org/{{:zoom}}/{{:tile.column}}/{{:tile.row}}.png",
  attr: "© OpenStreetMap & contributors, CC-BY-SA"
  style: { visibility: "hidden" } // default to hidden
}, {
  id: "Ortho_MapQuest",
  type: "tiled",
  src: function (view) {
    return "http://oatile" + ((view.index % 4) + 1) + ".mqcdn.com/naip/" + view.zoom + "/" + view.tile.column + "/" + view.tile.row + ".png";
  },
  attr: "<p>Tiles Courtesy of <a href='http://www.mapquest.com/' target='_blank'>MapQuest<a> <img src='http://developer.mapquest.com/content/osm/mq_logo.png'><p>"
} ];

// create a map with all services in place
var map = $( "#map" ).geomap( { services: services } );

To change visibility or opacity of a service after you have created the map, you should use the toggle or opacity methods.