Compass.js

Compass.js allows you to get compass heading in JavaScript. Today we haven’t any standard way to get compass data, but there are two proprietary APIs and one hack:

• PhoneGap has navigator.compass API.
• iOS Safari adds webkitCompassHeading property to deviceorientation event.
• We can enable GPS and ask user to go forward. GPS will send current heading, so we can calculate difference between real North and zero in deviceorientation event. Next we use this difference to get compass heading only by device orientation.

This library hides all this magic and APIs from you, autodetects available way and provides clean and simple API for your geolocation web app.

Usage

Hide compass for desktop users (without compass, GPS and accelerometers):

Compass.noSupport(function () {
  $('.compass').hide();
});

Show instructions for Android users:

Compass.needGPS(function () {
  $('.go-outside-message').show();          // Step 1: we need GPS signal
}).needMove(function () {
  $('.go-outside-message').hide()
  $('.move-and-hold-ahead-message').show(); // Step 2: user must go forward
}).init(function () {
  $('.move-and-hold-ahead-message').hide(); // GPS hack is enabled
});

Add compass heading listener:

Compass.watch(function (heading) {
  $('.degrees').text(heading);
  $('.compass').css('transform', 'rotate(' + (-heading) + 'deg)');
});

Method Name

Library will detect method asynchronously, so you can’t just read Compass.method, because it can be empty yet. It will be better to use Compass.init method:

Compass.init(function (method) {
  console.log('Compass heading by ' + method);
});

If library is already initialized, callback will be executed instantly, without reinitialization.

Unwatch

You can remove compass listener by Compass.unwatch method:

var watchID = Compass.watch(function (heading) {
  $('.degrees').text(heading);
});

Compass.unwatch(watchID);

Installing

Ruby on Rails

For Ruby on Rails you can use gem for Assets Pipeline.

1. Add compassjs gem to Gemfile:

   gem "compassjs"

2. Install gems:

   bundle install

3. Include Compass.js to your application.js.coffee:

   #= require compass

Others

If you don’t use any assets packaging manager (it’s very bad idea), you can use already minified version of the library.

Take it from: ai.github.io/compass.js/compass.js.

Contributing

1. To run tests you need node.js and npm. For example, in Ubuntu run:

   sudo apt-get install nodejs npm

2. Next install npm dependencies:

   npm install

3. Run all tests:

   npm test

4. Run test server:

   ./node_modules/.bin/cake server

5. Open tests in browser: localhost:8000.

6. Also you can see real usage example in integration test: localhost:8000/integration.