My First Firefox OS App

I just wrote my first Firefox OS App, and it was actually a lot easier than I expected it to be. That's partially the beauty of the web, where every app is just a container around a website. And partially a nice part about Mozilla - Everything is open source so Googling for an error usually comes up with a good answer. What I want to do over the next couple of days is walk through the deep stack that is a web browser - What happens if I request for my location? So first up, what happens at the high level? Let's build a basic Firefox OS app that gives us our geolocation.

First, we use the web geolocation API, which gives us access to our GPS coordinates. Let's start off with a simple website that asks for our location, then prints out the coordinates. Here's the source for our index.html:

<html>
  <head>
    <title>Get your Location</title>
  </head>
  <body>
    <script type="text/javascript">
    function updateGeoStatus(message) {
      var field = document.getElementById("geoStatus");
      field.innerHTML = message;
    }

    function successGeoLocation(position) {
      updateGeoStatus("Latitude: " + position.coords.latitude 
         + " Longitude: " + position.coords.longitude);
    }

    function errorLocation(error) {
      updateGeoStatus("Wrong position error. Error " + error.code + 
          " message is: " + error.message);
    }

    function geoLocation() {
      if ("geolocation" in navigator) {
        updateGeoStatus("Waiting on location\n");
        navigator.geolocation.getCurrentPosition(successGeoLocation, errorLocation); 
      } else {
        alert("No geolocation!\n");
      }
    }
    </script>
    <p><button onclick="geoLocation()">Get the location</button></p>

    <div id ="geoStatus">
      Hi World
    </div>

  </body>
</html>

If you save this on your server and just load it up in your desktop browser, it should work. Once we click the button to find our location, we get a message saying we're finding it, and once we resolve the location, we print the coordinates to the screen. Seems simple enough. Now how do we make this an app that we can actually install on a Firefox OS phone?

First, let's look up some documentation on building our application. We have to do two things: 1) Add a manifest file and 2) Add an installer. To add a manifest.webapp file, open up your favorite editor and create a manifest.webapp. The manifest file describes a few things about your app such as the name and where in the web your app exists. The best part is that Mozilla has a Firefox OS Manifest Validator to make sure you're doing everything right. Let's break down what's going on in the manifest:

{
  "name"            : "The Awesome App",
  "description"     : "Awesome League",
  "launch_path"     : "/~mchang/",
  "default_locale"  : "en",
  "developer"       : {
    "name"          : "Mason",
    "url"           : "http://masonchang.com"
  },

  "icons"           : {
    "16"  : "img/logo16.png",
    "32"  : "img/logo32.png",
    "64"  : "img/logo64.png",
    "128" : "img/logo128.png"
  },

  "permissions" : {
    "geolocation" : {
      "description" : "Testing Geolocation"
     }
  }
}

A manifest file is basically a JSON file with a few descriptions. You need your URL, Name, App name, and where the app lives relative to / on the home server.  Icons are your app icons in different resolutions. One interesting thing to note though is that the icons path is actually relative to /, even though we stated the launch_path to be ~mchang. This seems to be either a bug in FF OS itself or the online validator. I still have to investigate what's going on there.

Next you'll notice that we have a permissions JSON entry as well. This is required as geolocation needs to be explicitly enabled in our app in our manifest.webapp files. Otherwise, if you run the application, you'll get a permission denied error when your app tries to read the phone's location.

Second, you'll need to create another file that tells Firefox OS to install the app. Let's load up install.html!

<html>
  <head>
    <title>Hello Shu</title>
  </head>
  <body>

    <script type ="text/javascript">
      var manifest = "http://masonchang.com/manifest.webapp";
      var request = window.navigator.mozApps.install(manifest);
      request.onsuccess = function() {
        var appRecord = this.result;
        alert("Installation Success");
      }
      request.onerror = function() {
        alert("Error: " + this.error.name);
      }

    </script>
  </body>
</html>

Our install.html just has some JavaScript that loads up on page load, points to our manifest location, and tells the navigator to install the application.

Now we have 3 files. We have is our basic index.html file that is our actual app, the install.html file that tells Firefox OS how to install the app, and our manifest.webapp file and we have our first app! You can test the app in the Firefox OS Simulator or a real device if you have one. Point the simulator or device to your install.html file and you're good to go! Woohoo! Now, if you run the app, push the button, you'll get your geolocation in text! (Actually doesn't work in the Firefox OS Simulator, but it does on the device and desktop browser). Next blog post, how does Firefox OS actually get your location from your running JavaScript?