danmasta / angular-google-maps

A very easy to use google maps application for angular.js. At only 14kb minified, this is one of the smallest and most powerful google map integrations out there.

Simple Angular Google Maps

A very easy to use google maps application for angular.js. At only 12kb minified, this is one of the smallest and most powerful google map integrations out there.

Edit: This plugin is going through major changes, it will be updated/ replaced soon. Current version is not stable or production ready.

What this plugin does

Creates a google map element on your page. Configuration can be done with html tags and attributes, and can be styled with css.

Demo

Check out a demo with all features here: http://test.dev.danmasta.net/google-map-demo/

This plugin supports the following features

• Google maps direction service
• Google maps street view service
• HTML5 geolocation service
• Geolocation fallback if geolocation is not supported or not available
• Custom info window
• Autocomplete search input
• Marker animation
• Cusomizable map offset ( great when positioning autocomplete on top of map )
• Custom zoom buttons
• Custom marker images
• Custom streetview close button
• Keyboard support for autocomplete results
• Ajax/ Rest Api friendly marker loading
• Easy to override all default options for each Google maps service class

How it works

This plugin makes use angular directives to utilize each google maps service or functionality. There is one element required: <google-map>

The rest of the options can be added by setting attributes on any dom element. This allows for excellent customization of styles and user experience. If you were to utilize every option, the minimal code would look something like this:

<section ng-app="google-maps">
  <google-map offset="6" direction-service streetview-service preload="true" url="//someurl.whatever" params="param1:'value', param2:'value'"></google-map>
  <input type="text" name="search" placeholder="Search Map" autocomplete="off" auto-complete ng-model="search" />
  <ul auto-complete-results></ul>
  <div infowindow></div>
  <a zoom="in"></a>
  <a zoom="out"></a>
  <a street-view-open>Streetview Open</a>
  <div sreet-view-close>&times;</div>
  <div direction-info></div>
</section>

Dependencies

• Google Maps Api - //maps.google.com/maps/api/js?sensor=true
• Angular.js - //ajax.googleapis.com/ajax/libs/angularjs/1.2.12/angular.min.js
• Geometry library is needed only if using the direction service. Be sure to include the library parameter in your google api url like this: //maps.google.com/maps/api/js?sensor=true&libraries=geometry

Loading Markers

By default, markers are loaded using angular's $http service, and expects a json response of objects to use for markers. The marker service makes use of only three fields that are required, any other data returned is set inside of a data: property on each marker. This makes it really easy for you to customize the infowindow templates, dropdown select template, or add your own custom directives to extend and use the data however you like. The minimum fields for loading markers are:

latitude: '24.355678', //string - decimal format latitude integer
longitude: '-33.225563', //string - decimal format longitude integer
title: 'California', //string - optional, used as marker title and default infowindow text
id: 25 //string, integer - unique id of object, used in search service

Services

Markers
Method	Description
loadMarkers( url, params )	Accepts a url string, and an optional list of search parameters in json format param:'value'. Loads json objects from specified url, sends them to be parsed and added to map
parseMarkers( data )	Parses json objects into Google maps marker class objects. Requires latitude, and longitude properties
addMarker( marker, i )	Expects an already parsed google maps marker object and adds it to the map. Optional index parameter can be passed when adding multiple markers, this is used to set the delay for the marker drop animation
getMarkers()	Returns an object array of all the current markers loaded in the map
getMarkerById( id )	Returns a Google maps marker object by searching against the unique id passed when marker was first parsed.
Options
Method	Description
getOptions()	Returns a json object of Google maps service class options
Property	Description
mainBounds	google.maps.LatLngBounds class contructor
mapDefaults	google.maps.MapOptions object
markerImage	google.maps.Icon object
polyLineOptions	google.maps.PolylineOptions object
circleOptions	google.maps.CircleOptions object
panoramaOptions	google.maps.StreetViewPanoramaOptions object
Map
Method	Description
offSetMap( latlng )	Accepts a Google maps latlng object and 'offsets' the map to that position. The offset amount is based on the value defined in the offset attribute on the google-map element. The offset value is the denomiator for dividing the window width, if offset="6" then offset value equals window.width()/6
apply()	Runs angular $apply on the $rootScope to digest any outside changes
geo()	Returns a promise object with one function locate() which is used to run a callback after the future object has returned. Usage would look like this: map.geo().locate().then( function( position ) { //do stuff }); Note that this function has a fallback in case geolocation is not supported or fails, in either case the callback parameter is a google.maps.LatLng class
getDirections()	Returns a promise object with one function directions() which is used to run a callback after the future object has returned. Usage would look like this: map.getDirections().directions().then( function( directions ) { //do stuff }); Callback parameter is a google.maps.DirectionsResult object
getStreetview( marker )	Accepts a Google maps marker object and returns a promise object with one function streetview() which is used to run a callback after the future object has returned. Usage would look like this: map.getStreetview( marker ).streetview().then( function( position ) { //do stuff }); Callback parameter is a google.maps.StreetViewPanoramaData object
setVisible( element )	Accepts an angular or jQuery element object, lightly fades the element into view
setHidden( element )	Accepts an angular or jQuery element object, lightly fades the element out of view

Directives

Directives
Name	Type	Description
google-map	Element	A <google-map> element. This is the main element; the Google map will be built here. Supports 6 different options configured as attributes: [offset] - the amount to offset the map center [direction-service] - enables the direction service, and by dependency the geolocation service [streetview-service] - enables the streetview service [preload] - if preload equals true, it will load markers from the specified url on initialization [url] - the url to load json marker resources from [params] - search parameters to include in the marker request
zoom	Attribute	Defines the element to be used as a zoom button. To use just set an attribute of zoom="in" or zoom="out" on any dom element
info-window	Attribute	Defines the element to be used as the custom info window element. Provides a very basic default template for displaying title, and streetview open button. Template can be easily over written with custom structure
direction-service	Attribute	Enables the direction service, and gelocation service by dependency. Displays a route polyline on the map from current location to selected destination. Gets a google map direction object for the current location, stores this infomation in $scope.directions property
direction-info	Attribute	Defines the element to append distance/ duration info for the current route
streetview-service	Attribute	Enables the streetview service. Gets a google map streetview panorama object for the current location, sets the current map's panorama as this location's panorama id. When the streetview-open directive is triggered, the streetview service will be visible within the current map element
street-view-open	Attribute	Defines the element to be used as the trigger for opening the streetview in the current map element. If streetview service succeeds, this element will be visible for interaction, otherwise the element is hidden from view automatically, suggesting there is no streetview service for the current location
street-view-close	Attribute	Defines the element to be used as the trigger for closing the streetview in the current map element. This element is only visible when the streetview service is open
auto-complete	Attribute	Enables and defines the element to be used for auto complete style search functionality for all markers currently loaded in the map. This should be used on an input element. Supports keyboard interaction. Requires ng-model="search" attribute. Recommended usage is: <input type="text" name="search" placeholder="Search Map" autocomplete="off" auto-complete ng-model="search" />
auto-complete-results	Attribute	Enables and defines the element to be used as the auto-complete results container. Utilizes an ng-repeat template to build out the list of search results. Default template is a very simple <li> element, but you can very easily override this template to create any structure and data combination you want by using the data that was returned in the original json marker request. Any information that was returned is stored within the data: property of each marker. So you can access any property by utilizing {{data.whatever.property}} format

Events

Events
Event	Type	Scope	Description
marker.add	$broadcast	$rootScope	Event is broadcasted each time a marker is added to the map. Callback params are 'marker' and optional 'index'. Callback function would look like: $rootScope.$on( 'marker.add', function( marker, i ) { //do stuff });
search.focus	$broadcast	$rootScope	Event is broadcasted each time the [auto-complete] input comes into focus. There is no special data passed.
search.blur	$broadcast	$rootScope	Event is broadcasted each time the [auto-complete] input goes out of focus. There is no special data passed.
geo.complete	$emit	$scope	Event is emited when the [direction-service] controller has completed succesfully. Callback param is 'position'. Callback function would look like: $scope.$on( 'geo.complete', function( position ) { //do stuff });
streetview.success	$emit	$scope	Event is emited each time the [streetview-service] has completed successfully. Callback param is a Google maps streetview panorama data object. Callback function would look like: $scope.$on( 'streetview.success', function( data ) { //do stuff });
streetview.fail	$emit	$scope	Event is emited each time the [streetview-service] fails. Callback param is status.
streetview.open	$emit	$scope	Event is emited each time the [streetview-service] panorama is opened. There is no special data passed.
streetview.close	$emit	$scope	Event is emited each time the [streetview-service] panorama is closed. There is no special data passed.