type | Array |
---|---|
default | |
[ { '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'; }, style: { visibility: 'visible', opacity: 1.0 }, 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>' } ] ); |
|
init | |
One tiled service with Open Street Map: $( selector ).geomap( { services: [ { 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' } ] } ); Same service but using a template string: $( selector ).geomap( { services: [ { type: 'tiled', src: 'http://tile.openstreetmap.org/{{:zoom}}/{{:tile.column}}/{{:tile.row}}.png', attr: '© OpenStreetMap & contributors, CC-BY-SA' } ] } ); Tiled service with an empty shingled service for graphics, e.g., points of interest: $( selector ).geomap( { services: [ { type: 'tiled', src: 'http://tile.openstreetmap.org/{{:zoom}}/{{:tile.column}}/{{:tile.row}}.png', attr: '© OpenStreetMap & contributors, CC-BY-SA' }, { id: 'some-pois', type: 'shingled' }] } ); Shingled WMS service (MassGIS): Your service may require changes to $.geo.proj, tilingScheme, and bboxMax. See the shingled services example to see this in action. var massGisHost = 'http://giswebservices.massgis.state.ma.us/geoserver/wms'; var imageTemplate = '&SERVICE=WMS&VERSION=1.1.1&REQUEST=GetMap&FORMAT=image/png&SRS=EPSG:26986&BBOX={{:bbox}}&WIDTH={{:width}}&HEIGHT={{:height}}'; $( selector ).geomap( { services: [ { type: 'shingled', src: massGisHost + "?LAYERS=massgis_basemap" + imageTemplate, attr: '© 2011 Commonwealth of Massachusetts' } ] } ); |
|
get | var services = $( selector ).geomap( 'option', 'services' ); |
set | |
$( 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.
Service objects are JavaScript objects that control how the geomap widget displays maps, shapes, and other images.
Two of the service object's properties are required: type & src. The id and class properties are optional but at least one is recommended so you can target specific services with the toggle, opacity, and shape methods.
Some service types have service-specific properties to further configure how they operate.
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.
This is the most common type of service on the web as many map servers prerender tiles at speicifc scales for fast delivery.
Shingled services will get one image request each time the map refreshes. The bbox will be the extent of the current map view.
When panning, a shingled service will keep old images around and layer new images on top. This creates a shingling effect and, when previously viewed areas are panned back into view, the user will see the old images while waiting for the latest one to load.
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.
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.
The src property of a service object can be one of the following options:
For tiled services, the image is placed at the tile location specified. For shingled and image 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.
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.
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.
This property is for shingled and image services. It limits the number of images the services will keep around after sequential panning motions. It is useful to limit the number of shingles to 1 if you have a map service which returns images having transparent areas and/or data that updates frequently or based on the current view. Otherwise, old data (from the previously viewed shingles) will be visible and may be out of date or in the wrong place, e.g., server-generated labels which change depending on even slight variations of the bounding box.
$('#map').geomap( { services: [ { type: 'shingled', src: 'http://test.jquerygeo.com/wms?LAYERS=transparent_labels&SERVICE=WMS&VERSION=1.3.0&REQUEST=GetMap&FORMAT=image%2Fpng&TRANSPARENT=true&BBOX={{:bbox}}&WIDTH={{:width}}&HEIGHT={{:height}}', shinglesMax: 1 } ] } );
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.