mkly / nggeolocation

AngularJS support for HTML5 Geolocation

ngGeolocation

AngularJS support for HTML5 Geolocation API

ngGeolocation provides AngularJS support for the HTML5 Geolocation API. It aims to provide a quick and easy way to consume geolocation information made available by modern browsers and HTML5 in AngularJS apps wtihout having to write custom SDK wrapping code. Everything exposed by the $geolocation service lives within the digest cycle, so there is no need to use $scope.$apply() in your controllers when consuming the service. ngGeolocation goes one step further than wrapping the HTML5 API calls and provides a property that can be $watched by your controllers which will always contain the latest position data available through the browser.

API Reference

Installation

Bower

The bower package name is ngGeolocation.

via bower.json

{
    "dependencies": {
        "ngGeolocation": ">=0.0.2"
    }
}

via CLI

bower install ngGeolocation

Include the installed scripts in your html...

<script src="bower_components/ngGeolocation.min.js"/>

Manual

Download the minified or unminified source.

Include the scripts in your html...

<script src="lib/ngGeolocation.min.js"/>

Usage

Make sure your app depends on the ngGeolocation module. Geolocation methods are available through the $geolocation service.

angular
    .module('myApp', ['ngGeolocation'])
    .controller('geolocCtrl', ['$geolocation', '$scope', function($geolocation, $scope) {
         $geolocation.getCurrentPosition({
            timeout: 60000
         }).then(function(position) {
            $scope.myPosition = position;
         });
    }]);

The $geolocation service can expose a property location whose value reflects the current position. To enable this feature a watch must be created using watchPosition. This method takes a PositionOptions object in the same manner as getCurrentPosition. There is no return value.

While this watch is active the value of the property location is periodically updated with the latest geolocation result. If an error has occurred the code and message are available via $geolocation.position.error.

The current watch can be cancelled using clearWatch.

angular
    .module('myApp', ['ngGeolocation'])
    .controller('geolocCtrl', ['$geolocation', '$scope', function($geolocation, $scope) {
        $geolocation.watchPosition({
            timeout: 60000,
            maximumAge: 250,
            enableHighAccuracy: true
        });
        $scope.myPosition = $geolocation.position; // this object updates regularly, it has 'error' property which is a 'truthy' and also 'code' and 'message' property if an error occurs
        
        //It has all the location data 
        '$scope.myPosition.coords'
        
        //It's truthy and gets defined when error occurs 
        '$scope.myPosition.error'
    }]);

Usage with angular-google-maps

Here's an example from @markmcdonald51 for using ngGeolocation with angular-google-maps...

angular
.module('MyApp', ['ngGeolocation', 'google-maps'])
.controller('geolocCtrl', ['$geolocation', '$scope', function($geolocation, $scope) {

  $geolocation.watchPosition({
    timeout: 60000,
    maximumAge: 250,
    enableHighAccuracy: true
  })

  $scope.$watch('myPosition.coords', function (newValue, oldValue) {
    $scope.map = {
      center: {
        latitude: newValue.latitude,
        longitude: newValue.longitude
      },
      zoom: 16
    };                      
  }, true);

});

Development

This project uses Grunt for tooling. The toolbelt dependencies are managed by NPM and the production code dependencies are managed by Bower. Fork the code and clone it into your workspace, then...

npm install
bower install --dev

Tests can be run manually with grunt test or automatically on changes with grunt.

NB The minified file is generated by grunt build - all console logging is stripped out of the minified file using grunt-strip.

Contributions

If you wish to contribute, please raise an issue or submit a pull request which includes:

• A test or tests that demonstrate the issue found or feature added
• A rebuilt minified file (ngGeolocation.min.js)