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.

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)');
});

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.

You can remove compass listener by Compass.unwatch method:

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

Compass.unwatch(watchID);

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

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.

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.