Landcarte - a Google Maps jQuery plugin

Landcarte is a jQuery plugin and a JavaScript library that helps introduce geographic maps and their numerous features (including geocoding, geolocation, user events, markers and layers) onto a web page in a simple and concise way. In its core, Landcarte is based on the Google Maps API v3 and jQuery.

Landcarte provides access to the features of one of the most popular map APIs in a handy jQuery-like way. Its compact syntax helps reduce recurrent lengthy constructions of the API and also provides a more concise and straightforward way to deal with the basic geographical formats.

• denizli escort
• denizli escort
• didim escort
• düzce escort
• edirne escort
• edirne escort
• edremit escort

Brief Overview

Initialization

A map instance is initialized and reused via the .geoMap() method called on a jQuery object of the map container:

$("#map").geoMap();

var map = $("#map").geoMap({ center: [50, 12], zoom: 10 });

Overlays and Layers

map.add("markers", [[50.5, 15.5], [56.5, 10.5]], { icon: "m.png" })
   .add("layer.bicycling")
   .add("polyline", {
      path: [[48.92, 2.24], [46.19, 6.06], [48.19, 16.35]],
      strokeColor: "#f00", strokeWeight: 3, strokeStyle: "dotted"
   });

Selectors

var markers  = map.find("markers");
var shapes   = map.find("shapes:odd");
var polyline = map.find("polylines:visible").eq(2);
var marker   = map.find("marker:last");

Attributes and Properties

map.attr("center", [46.5, 8]);
marker.prop({ position: [46.5, 8], title: "Pointer" });
polyline.attr({ strokeStyle: "3px dotted #c09" });

Collection Iterator

map.find("markers").each(function(i, marker) {
   marker.attr({ title: "Marker #" + i });
});

Events

var balloon = map.balloon();
map.find("markers").on("click", function(event) {
   var p = event.target.prop("position");
   balloon.attr({ position: p, content: p.lat + ", " + p.lon }).show();
});

Geocoding

map.search("Copenhagen", function(data) {
   if (data.location) map.add("marker", data.location);
});

Brief Guide

Since the Landcarte framework relies both on jQuery and the Google Maps API v3, they should be included into the page in the first place.

<script type="text/javascript"
   src="//maps.googleapis.com/maps/api/js?sensor=false"></script>
<script type="text/javascript"
   src="//code.jquery.com/jquery-latest.min.js"></script>

A map instance is initialized and reused via the .geoMap() method called on a jQuery object of the map container:

$("#map").geoMap();

That's it. Further, this code is easily extended to something more practical:

Example

A map with clickable markers showing their location:

var star = { url: "star.png", anchor: { x: 10, y: 10 } };
var points = [
   [-17.5, -149.77], [-17.54, -149.57], [-17.56, -149.6],
   [-17.63, -149.61], [-17.69, -149.58]
];

// initializing a map instance and adding markers and a polyline
var map = $("#map").geoMap({ center: [-17.6, -149.63], zoom: 10 })
   .add("markers", points, { icon: star })
   .add("polyline", points);

// initializing an info balloon
var balloon = map.balloon().hide();

// attaching a click handler to the markers
map.find("markers").on("click", function(event) {
   var p = event.target.prop("position");
   // displaying the result of the geocoding request
   map.search(p, function(data) {
      balloon.attr({ position: p, content: data.locality }).show();
   });
});
			
// restyling the polyline
map.find("polyline").attr({ strokeStyle: "3px dotted #c09" });

Landcarte Reference

Map instance initialization

A map instance is initialized via a .geoMap([options:Object]) method call on the map container jQuery object, which returns an instance of at.geo.Map:

var map = $("#map").geoMap();

The same call can be used to get an already existing map instance and, optionally, to pass attributes to it. The map options are inherited from google.maps.MapOptions, yet a wider range of formats is accepted.

var options = { center: [50, 10], zoom: 3, mapTypeId: "roadmap" };
map = $("#map").geoMap(options);
// equivalent to
map = $("#map").geoMap().attr(options);

at.geo.Map

An instance of this class is returned by the .geoMap() method. This class is also an extension of at.geo.Object.

// an instance of at.geo.Map:
var map = $("#map").geoMap();

var d = map.distance([48.92, 2.24], [46.19, 6.06]); // ~417 km

.add("marker", options:Object|Array)

adds a marker to the map; the options can be either a set of marker options (inherited from google.maps.MarkerOptions) or coordinates.

map.add("marker", [50, 10]);
map.add("marker", { position: [50, 10], icon: "m.png" });

.add("markers", options:Array<Object|Array>, [sharedOptions:Object])

adds markers to the map; the options can be either an array of marker options (inherited from google.maps.MarkerOptions) or an array of coordinates; all shared marker options can be passed in as a separate sharedOptions argument.

map.add("markers", [[50.5, 15.5], [56.5, 10.5]]);
map.add("markers", [
   { position: [50.5, 15.5], label: "<b>#1</b>" },
   { position: [56.5, 10.5], label: "#2" }
]);
map.add("markers", [
   { position: [50.5, 15.5], icon: "a.png" },
   { position: [56.5, 10.5], icon: "b.png" }
]);
map.add("markers", [[50.5, 15.5], [56.5, 10.5]], { icon: "m.png" });

.add("polyline", options:Object|Array)

adds a polyline to the map; the options can be either a set of polyline options (inherited from google.maps.PolylineOptions) or an array of vertex coordinates; in addition, polylines also support the strokeStyle property, which can take one of the following values: "solid" (default), "dashed", "dotted"; alternatively, the strokeStyle can be defined in CSS border terms, e.g. "3px solid #f0c".

map.add("polyline", [[48.92, 2.24], [46.19, 6.06], [48.19, 16.35]]);
map.add("polyline", {
   path: [[48.92, 2.24], [46.19, 6.06], [48.19, 16.35]],
   strokeColor: "#f00", strokeWeight: 3, strokeStyle: "dotted"
});
map.add("polyline", {
   path: [[48.92, 2.24], [46.19, 6.06], [48.19, 16.35]],
   strokeStyle: "3px dotted #f0c"
});

.add("polygon", options:Object|Array)

adds a polygon to the map; the options can be either a set of polygon options (inherited from google.maps.PolygonOptions) or an array of vertex coordinates.

map.add("polygon", [[48.92, 2.24], [46.19, 6.06], [48.19, 16.35]]);
map.add("polygon", {
   paths: [[48.92, 2.24], [46.19, 6.06], [48.19, 16.35]],
   fillColor: "#f0f", strokeColor: "#f00", strokeWeight: 3
});

.add("rectangle", options:Object)

adds a rectangle to the map; the rectangle options are inherited fromgoogle.maps.RectangleOptions.

map.add("rectangle", {
   bounds: [[50.5, 10.5], [56.5, 15.5]],
   strokeColor: "#0f0", fillColor: "#0f0"
});

.add("circle", options:Object)

adds a circle to the map; the circle options are inherited fromgoogle.maps.CircleOptions.

map.add("circle", {
   center: [50.5, 10.5], radius: 54321,
   strokeColor: "#0f0", fillColor: "#0f0"
});

.add("layer.<type>", [options])

adds a layer to the map; the layer types include: "kml", "fusiontable", "traffic", "transit", "bicycling", "panoramio", "weather", "clouds" and "heatmap"; see the Google Maps reference for more details on the appropriate layer options.

NB: some layer types require an extra Google Maps Library to be included.

map.add("layer.traffic").add("layer.bicycling");

.find(selector:String) at.geo.Collection

returns a collection of geo-objects that match the selector; if the selector contains the :first or :last pseudo-class the method returns a single instance ofat.geo.Object instead of a collection; see the list of types and selectors.

var markers = map.find("markers");
var oddShapes = map.find("shapes", function(i) { return i % 2; });
// this is also equivalent to
oddShapes = map.find("shapes:odd");

.has(type:String) Number

determines whether there are geo-objects of the given type on the map; returns the number of geo-objects of the given type; see the list of available types at the .find()method.

if (map.has("polylines")) map.find("markers").fit();

.fit(bounds:Object|Array|String, [callback:function])

fits the map viewport to the given bounds or region; see alsoat.geo.Collection.fit().

.animate(options:Object)

if the options contain a center or bounds property, the map can get animated while the options are set; other properties are set instantly; the options.center can be either a pair of coordinates or can specify a pixelwise shift as {x, y}.

map.animate({ center: [50, 10] });
map.animate({ center: { x: -30, y: 25 } });

.animate(property:String, value)

if the property is "center" or "bounds", the map can get animated while the property is set; other properties are set instantly; the "center" property can be either a pair ofcoordinates or can specify a pixelwise shift as {x, y}.

map.animate("center", [50, 10]);
map.animate("center", { x: -30, y: 25 });

.balloon([options:Object]) at.geo.Object

creates an instance of the info balloon; options are inherited fromgoogle.maps.InfoWindowOptions.

var balloon = map.balloon();
map.find("markers").on("click", function(e) {
   var p = e.target.prop("position");
   balloon.attr({ position: p, content: p.lat + ", " + p.lon }).show();
});

.panorama([options:Object]) at.geo.Object

creates an instance of the street view panorama; options are inherited fromgoogle.maps.StreetViewPanoramaOptions.

map.panorama().toggle();

.clusterize([options:Object], [function:filter(index:Number)])

clusters markers.

NB: the markerclusterer.js library should be included.

if (map.clusterized()) map.declusterize();
else map.clusterize();

.declusterize()

unclusters markers.

NB: the markerclusterer.js library should be included.

.clusterized() boolean

determines whether the map markers are clustered.

.distance(p1:Array|Object, p2:Array|Object) Number

returns the distance between two locations in kilometers; each of the locations is represented by a pair of coordinates.

.search(location:String|Object|Array, [callback:function(data)])

makes a geocoding request for the given location which is either a string address or a pair of coordinates.

map.search("Berlin", function(data) {
   if (data.location) map.add("marker", data.location);
});

.search(options:Object)

makes a geocoding request for the given options.location or options.query which is either a string address or a pair of coordinates; options can also specify a regionand/or bounds to search within; callbacks can be passed to the method asoptions.complete, options.success and/or options.error.

map.search({
   query: "Prague", 
   complete: function(data) { ... }
});

.route(options:Object, [callback:function(data)])

renders a route according to the options (see google.maps.DirectionsRequest); default options.travelMode is "driving"; the route directions can be rendered in a DOM element, if options.panel is specified; the method removes the route if null is passed as an argument.

map.route({
   origin: "Grenoble", destination: "Paris",
   waypoints: [{ location: "Annecy" }]
});
map.route(null);

.remove()

removes the map instance from the container.

map.remove();

.remove(object:String|at.geo.Object)

removes all geo-objects matching the given object, which can be either a string designation of the objects' type to be removed or a specific object itself; equivalent to.find(type).remove(); see the list of available types at the .find() method.

map.remove("markers").remove("shapes");

See also at.geo.Object to learn about the inherited methods.

at.geo.Object

The map (an instance of at.geo.Map) and almost anything added to the map are extensions of this class, therefore they inherit the methods of this class.

// instances of at.geo.Object:
var map      = $("#map").geoMap();
var marker   = map.find("markers").eq(0);
var polyline = map.find("polylines").eq(2);
var balloon  = map.balloon();

.attr(options:Object)

passes a set of attributes to the geo-object.

marker.attr({ position: [46.5, 8] });

.attr(name:String, value)

passes a single attribute to the geo-object.

map.attr("center", [46.5, 8]);

.attr(name:String) dynamic type

returns an attribute from the geo-object; this method returns a raw value provided by the map engine; see also the .prop() method.

var color = polyline.attr("strokeColor");
var p = marker.attr("position"); // raw internal output

.prop(options:Object)

passes a set of properties to the geo-object.

marker.prop({ position: [46.5, 8] });

.prop(name:String, value)

passes a single property to the geo-object.

map.prop("center", [46.5, 8]);

.prop(name:String) dynamic type

returns a property from the geo-object; this method returns a normalized value which wraps the value provided by the map engine; see also the .attr() method.

var color = polyline.prop("strokeColor");
var p = marker.prop("position"); // normalized output

.show()

makes the geo-object visible.

marker.show();

.hide()

makes the geo-object invisible.

marker.hide();

.toggle([property:String])

switches the geo-object's visibility, if no property is passed; otherwise switches a boolean property of the geo-object to the reverse.

marker.toggle();
polyline.toggle("editable");

.on(events:String, handler:function(event:Object))

attaches an event handler for one or more events to the geo-object; the events argument is an event type or a space-separated list of event types; the handler function is an event handler; within the scope of the event handler, this keyword refers to the raw geo-object provided by the map engine, and the event.target is its at.geo.Objectcounterpart.

marker.on("click", function(event) {
   var p = event.target.prop("position");
   balloon.show({ position: p, content: p.lat + ", " + p.lon });
});
// for labelled markers, "label" prefixed events are also available
marker.on("label.click", function(event) {
   var p = event.target.prop("position");
   balloon.show({ position: p, content: this.title });
});

.off(events:String)

detaches all event handlers of the given types from the geo-object; the events argument is an event type or a space-separated list of event types.

polyline.off("click");

.trigger(event:String)

calls the handlers of the given event type attached to the geo-object.

polyline.trigger("click");

.bounds() Object

returns the bounding box outlining the geo-object.

.fit()

fits the map viewport to the geo-object.

// fitting to the first polygon on the map
map.find("polygon").eq(0).fit();

.remove()

removes the geo-object; at.geo.Map extends this method, seeat.geo.Map.remove().

polyline.remove();

.is(type:String) boolean

determines whether the geo-object is of the given type.

polyline.core.type == "shape"; // false, since the type is "polyline"
polyline.is("polyline"); // true
polyline.is("shape"); // true

.core Object

stores a reference to the internal raw geo-object.

at.geo.Collection

This class represents a collection of geo-objects. Many of its methods are identical to the methods of at.geo.Object, which makes interaction with a collection of geo-objects almost identical to the interaction with a single geo-object.

var map = $("#map").geoMap();
// instances of at.geo.Collection:
var markers     = map.find("markers");
var polylines   = map.find("polylines");
var greenShapes = map.find("shapes", { fillColor: "green" });

.eq(n:Number) at.geo.Object

returns a geo-object at the n-th index position in the collection.

.first() at.geo.Object

returns the first geo-object in the collection.

.last() at.geo.Object

returns the last geo-object in the collection.

.gt(n:Number) at.geo.Collection

returns a subset collection of the geo-objects with the index position greater than n.

.lt(n:Number) at.geo.Collection

returns a subset collection of the geo-objects with the index position less than n.

.get(n:Number) Object

returns a raw geo-object at the n-th index position in the collection.

.each(iterator:function(index:Number, object:at.geo.Object))

iterates over the collection of geo-objects; within the scope of the iterator function,this keyword refers to the raw geo-object linked to the object passed as an argument.

markers.each(function(i, marker) {
   marker.prop("title", "Marker #" + (i + 1));
});

.attr(options:Object)

passes a set of attributes to the collection of geo-objects.

.attr(name:String, value)

passes a single attribute to the collection of geo-objects.

.attr(name:String) Array

returns an array of attributes from the collection of geo-objects; this method returns raw values provided by the map engine; see also the .prop() method.

.prop(options:Object)

passes a set of properties to the collection of geo-objects.

.prop(name:String, value)

passes a single property to the collection of geo-objects.

.prop(name:String) Array

returns an array of properties from the collection of geo-objects; this method returns normalized values which wrap the values provided by the map engine; see also the.attr() method.

.show()

makes the geo-objects in the collection visible.

.hide()

makes the geo-objects in the collection invisible.

.toggle([property:String])

switches the visibility of the geo-objects in the collection, if no property is passed; otherwise switches a boolean property of the collection to the reverse.

.on(events:String, handler:function(event:Object))

attaches an event handler for one or more events to the collection of geo-objects; seeat.geo.Object.on().

.off(events:String)

detaches all event handlers of the given types from the collection of geo-objects; seeat.geo.Object.off().

.trigger(event:String)

calls the handlers of the given event type attached to the collection of geo-objects.

.bounds() Object

returns the bounding box outlining the collection of geo-objects.

.fit()

fits the map viewport to the given collection of geo-objects.

// fitting to all markers except for the first three
map.find("markers").gt(2).fit();

.remove()

removes all geo-objects in the collection.

.filter(test:function(index:Number, object:at.geo.Object))

returns the subset of the collection passing the function test as true; within the scope of the test function this keyword refers to the raw counterpart of the object.

.filter(properties:Object)

returns the subset of the collection matching the given set of properties.

.filter(pseudoclass:String)

returns the subset of the collection matching the given pseudo-class.

.toArray() Array<at.geo.Object>

returns the array of the geo-objects in the collection.

.size() Number

returns the number of geo-objects in the collection.

.empty() boolean

determines whether the collection is empty.

Geo-object options

The representation of geo-object options is inherited from the Google Maps API v3. Still, in Landcarte certain options can be passed in several ways which are quite common but not natively supported by the Google API.

Coordinates can be presented in almost any conceivable way, e.g.:

[ 46.233921, 6.052458 ]
{ lat: 46.233921, lon: 6.052458 }
{ latitude: 46.233921, longitude: 6.052458 }

Rectangular bounds are likewise defined by a couple of south–west and north–east points, e.g.:

[ [45, 3], [55, 12] ]
{ sw: [45, 3], ne: [55, 12] }
{ sw: { lat: 45, lon: 3 }, ne: { lat: 55, lon: 12 } }

Some constants can be passed as text strings, e.g.:

// { mapTypeId: google.maps.MapTypeId.HYBRID }
{ mapTypeId: "hybrid" }

Types of geo-objects

Supported types of geo-objects include "marker", "shape", "polyline", "polygon", "rectangle", "circle", "layer" (as well as the specific layer types), "balloon", "panorama" and, alternatively, their plurals.

Selectors

Supported selectors include all types of geo-objects and their combinations with the following pseudo-classes: :first, :last, :visible, :invisible, :odd,:even.

Geo-object events

To all types of the geo-objects event handlers can be attached via the .on() method and detached via the .off() method. The names of the events, available on each of the geo-object types, are equivalent to those provided by the Google Maps API v3 with underscores removed — to better comply with the native JavaScript event naming notation.

var map = $("#map").geoMap();
map.find("shapes").on("click", function(event) {
   map.add("marker", event.location);
});
map.find("circles").off("click");