Simulator Walkthrough

  • Revision slug: Tools/Firefox_OS_Simulator/Simulator_Walkthrough
  • Revision title: Simulator Walkthrough
  • Revision id: 385181
  • Created:
  • Creator: wbamberg
  • Is current revision? No
  • Comment

Revision Content

In this page we'll debug a very simple (but very buggy!) web app using the Firefox OS Simulator.

The walkthrough is structured into three parts: each part uses a different diagnostic/debugging tool, specifically, manifest validation, the Error Console, and the JavaScript Debugger. It's intended that each part should be self-contained, so it should be possible to read only that part and have it make sense.

Using manifest validation

If you want to follow along, the various revisions of the app are in the firefoxos-simulator-walkthrough repository on GitHub, and you can pick the walkthrough up at this point by starting with the whereami-1 version of the app.

The app displays a single button labeled "Where am I?". When the user clicks the button, the app fetches the user's current location using the Geolocation API, and displays it on a map.

The walkthrough assumes that you've installed the Simulator and opened the Dashboard.

First we'll add the app to the Dashboard by clicking "Add Directory" and selecting the manifest. We'll see this:



Clicking on "(1 errors and 1 warnings)"  we see this:


This error message is pretty clear, and if we look at "manifest.webapp", we can see that it's missing a "name":

{
  "description": "A simple web app",
  "launch_path": "/index.html",
  "icons": {
    "128": "/style/icons/earth.png"
  }
}


Add the "name" field to the manifest file, save it, and click "Update" in the Dashboard:

{
  "name": "Where am I?",
  "description": "A simple web app",
  "launch_path": "/index.html",
  "icons": {
    "128": "/style/icons/earth.png"
  }
}


This time the Dashboard should tell us that we have no errors, and should run the app:

But when you click the button, nothing happens. In the next section, we'll try using the Error Console to diagnose this problem.

Using the Error Console

If you haven't followed along from the start of this walkthrough:

In this section we'll debug a very simple (but very buggy!) web app using the Firefox OS Simulator. The various versions of the app are in the firefoxos-simulator-walkthrough repository on GitHub, and you can pick the walkthrough up at this point by starting with the whereami-2 version.

The app displays a single button labeled "Where am I?". When the user clicks the button, the app fetches the user's current location using the Geolocation API, and displays it on a map.

But in this version, when we click the button nothing happens. In this section of the walkthrough, we'll use the Error Console to try to diagnose the problem.

The walkthrough assumes that you've installed the Simulator, opened the Dashboard, and added the app by clicking "Add Directory" in the Dashboard, then selecting the app's "manifest.webapp" file.

Over in the Dashboard, click "Running" to stop the Simulator, and check the box labeled "Console":

Now click "Run" over on the right-hand side, and the Error Console should launch alongside the app. In the console output you might see a few errors, warnings, and messages, but the last one in particular looks relevant:



This is obviously a problem in our app's script, "whereami.js". Here are the first few lines of the script:

var whereami = document.getElementById('whereami');

whereami.onclick = function() {
  navigator.geolocation.getCurrentPosition(getMap, error);
};


Comparing this with our app's "index.html", the problem's obvious:

<!DOCTYPE html>

<html>

  <head>
    <meta charset='utf-8'>
    <script src="http://open.mapquestapi.com/sdk/js/v7.0.s/mqa.toolkit.js"></script>
    <script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/jquery/1.6.2/jquery.min.js"></script>

  </head>

  <body>
    <button id ="where-am-i">Where am I?</button>
    <div id="map"></div>
    <script src="scripts/whereami.js"></script>
    <link media="all" href="style/style.css" type="text/css" rel="stylesheet">
  </body>

</html>


In the HTML, the button is assigned an ID of "where-am-i", but in the JavaScript, we're trying to use "whereami". So let's fix that:

var whereami = document.getElementById('where-am-i');

whereami.onclick = function() {
  navigator.geolocation.getCurrentPosition(getMap, error);
};

Now the app starts up without any errors, but when we click the button, the map doesn't appear, and we get a new message in the console:

This message is logged by our "whereami.js" script, and indicates that the geolocation API has returned an error - but it unhelpfully doesn't tell us what the error was. We can use the JavaScript Debugger to figure that out.

Using the JavaScript Debugger

If you haven't followed along from the start of this walkthrough:

In this section we'll debug a very simple (but very buggy!) web app using the Firefox OS Simulator. The various versions of the app are in the firefoxos-simulator-walkthrough repository on GitHub, and you can pick the walkthrough up at this point by starting with the whereami-3 version.

The app displays a single button labeled "Where am I?". When the user clicks the button, the app fetches the user's current location using the Geolocation API, and displays it on a map.

But in this version, when we click the button the Geolocation API returns an error. In this section of the walkthrough, we'll use the JavaScript Debugger to figure out exactly which error is returned.

The walkthrough assumes that you've installed the Simulator, opened the Dashboard, and added the app by clicking "Add Directory" in the Dashboard, then selecting the app's "manifest.webapp" file.

In the Dashboard, click the "Connect" button:


Then click "Connect" in the new page that appears, then select "chrome://prosthesis/content/shell.xul" in the next page. You should see the developer tools window:


Click "Debugger", and you'll see the app's script:


According to the Geolocation API reference, the specific error is given by the code property of the error object that's passed into the error handler error(). So set a breakpoint inside error() by clicking to the left of line 8:

In the app, click "Where am I?". Execution should stop at the breakpoint:


Click where it says "Add watch expression" and type "error.code", and you'll immediately see its value, "1":


According to the Geolocation API documentation, "1" means "Permission denied". This is an error web apps get if they have not requested the geolocation permission, or if the permission wasn't granted by the user.

Looking at the "manifest.webapp" file, we'll see that we didn't ask for the permission:

{
  "name": "Where am I?",
  "description": "A simple web app",
  "launch_path": "/index.html",
  "icons": {
    "128": "/style/icons/earth.png"
  }
}


Let's fix that:

{
  "name": "Where am I?",
  "description": "A simple web app",
  "launch_path": "/index.html",
  "icons": {
    "128": "/style/icons/earth.png"
  },
  "permissions": {
    "geolocation": {
      "description": "Needed to tell the user where they are"
      }
  }
}


Save "manifest.webapp", and click "Update" in the Dashboard one more time. This time the app runs, and when you click "Where am I?" it asks you to share your location, and if you allow it, the app displays the map:

Revision Source

<p>In this page we'll debug a very simple (but very buggy!) web app using the <a href="/en-US/docs/Tools/Firefox_OS_Simulator" title="/en-US/docs/Tools/Firefox_OS_Simulator">Firefox OS Simulator</a>.</p>
<p>The walkthrough is structured into three parts: each part uses a different diagnostic/debugging tool, specifically, <a href="#Using-manifest-validation" title="#Using-manifest-validation">manifest validation</a>, <a href="#Using-the-Error-Console" title="#Using-the-Error-Console">the Error Console</a>, and <a href="#Using-the-JavaScript-Debugger" title="#Using-the-JavaScript-Debugger">the JavaScript Debugger</a>. It's intended that each part should be self-contained, so it should be possible to read only that part and have it make sense.</p>
<h3 id="Using_manifest_validation"><a name="Using-manifest-validation">Using manifest validation</a></h3>
<div class="note">
  <p>If you want to follow along, the various revisions of the app are in the <a href="https://github.com/wbamberg/firefoxos-simulator-walkthrough" title="https://github.com/wbamberg/firefoxos-simulator-walkthrough">firefoxos-simulator-walkthrough</a> repository on GitHub, and you can pick the walkthrough up at this point by starting with the <a href="https://github.com/wbamberg/firefoxos-simulator-walkthrough/tree/master/whereami-1" title="https://github.com/wbamberg/firefoxos-simulator-walkthrough/tree/master/whereami-1">whereami-1</a> version of the app.</p>
  <p>The app displays a single button labeled "Where am I?". When the user clicks the button, the app fetches the user's current location using the Geolocation API, and displays it on a map.</p>
  <p>The walkthrough assumes that you've <a href="/en-US/docs/Tools/Firefox_OS_Simulator#Installing_the_Simulator_add-on" title="/en-US/docs/Tools/Firefox_OS_Simulator#Installing_the_Simulator_add-on">installed the Simulator</a> and opened the Dashboard.</p>
</div>
<p>First we'll add the app to the Dashboard by clicking "Add Directory" and selecting the manifest. We'll see this:</p>
<p><img alt="" src="https://mdn.mozillademos.org/files/5207/manifest-error-collapsed.png" style="width: 791px; height: 634px;" /><br />
  <br />
  Clicking on "(1 errors and 1 warnings)"&nbsp; we see this:</p>
<p><img alt="" src="https://mdn.mozillademos.org/files/5209/manifest-error-expanded.png" style="width: 791px; height: 634px;" /><br />
  This error message is pretty clear, and if we look at "manifest.webapp", we can see that it's missing a "name":</p>
<pre>
{
&nbsp; "description": "A simple web app",
&nbsp; "launch_path": "/index.html",
&nbsp; "icons": {
&nbsp;&nbsp;&nbsp; "128": "/style/icons/earth.png"
&nbsp; }
}</pre>
<p><br />
  Add the "name" field to the manifest file, save it, and click "Update" in the Dashboard:</p>
<pre>
{
&nbsp; "name": "Where am I?",
&nbsp; "description": "A simple web app",
&nbsp; "launch_path": "/index.html",
&nbsp; "icons": {
&nbsp;&nbsp;&nbsp; "128": "/style/icons/earth.png"
&nbsp; }
}</pre>
<p><br />
  This time the Dashboard should tell us that we have no errors, and should run the app:</p>
<p><img alt="" src="https://mdn.mozillademos.org/files/5213/whereami-nomap.png" style="width: 400px; height: 606px;" /></p>
<p>But when you click the button, nothing happens. In the next section, we'll try using the Error Console to diagnose this problem.</p>
<h3 id="Using_the_Error_Console"><a name="Using-the-Error-Console">Using the Error Console</a></h3>
<div class="note">
  <p><strong>If you haven't followed along from the start of this walkthrough:</strong></p>
  <p>In this section we'll debug a very simple (but very buggy!) web app using the <a href="https://developer.mozilla.org/en-US/docs/Tools/Firefox_OS_Simulator" title="/en-US/docs/Tools/Firefox_OS_Simulator">Firefox OS Simulator</a>. The various versions of the app are in the <a href="https://github.com/wbamberg/firefoxos-simulator-walkthrough" title="https://github.com/wbamberg/firefoxos-simulator-walkthrough">firefoxos-simulator-walkthrough</a> repository on GitHub, and you can pick the walkthrough up at this point by starting with the <a href="https://github.com/wbamberg/firefoxos-simulator-walkthrough/tree/master/whereami-2" title="https://github.com/wbamberg/firefoxos-simulator-walkthrough/tree/master/whereami-1">whereami-2</a> version.</p>
  <p>The app displays a single button labeled "Where am I?". When the user clicks the button, the app fetches the user's current location using the Geolocation API, and displays it on a map.</p>
  <p>But in this version, when we click the button nothing happens. In this section of the walkthrough, we'll use the Error Console to try to diagnose the problem.</p>
  The walkthrough assumes that you've <a href="/en-US/docs/Tools/Firefox_OS_Simulator#Installing_the_Simulator_add-on" title="/en-US/docs/Tools/Firefox_OS_Simulator#Installing_the_Simulator_add-on">installed the Simulator</a>, opened the Dashboard, and added the app by clicking "Add Directory" in the Dashboard, then selecting the app's "manifest.webapp" file.</div>
<p>Over in the Dashboard, click "Running" to stop the Simulator, and check the box labeled "Console":</p>
<p><img alt="" src="https://mdn.mozillademos.org/files/5195/dashboard-connect-box.png" style="width: 791px; height: 634px;" /></p>
<p>Now click "Run" over on the right-hand side, and the Error Console should launch alongside the app. In the console output you might see a few errors, warnings, and messages, but the last one in particular looks relevant:<br />
  <br />
  <img alt="" src="https://mdn.mozillademos.org/files/5215/error-console-whereami-message.png" style="width: 720px; height: 560px;" /><br />
  <br />
  This is obviously a problem in our app's script, "whereami.js". Here are the first few lines of the script:</p>
<pre class="brush: js">
var whereami = document.getElementById('whereami');

whereami.onclick = function() {
&nbsp; navigator.geolocation.getCurrentPosition(getMap, error);
};</pre>
<p><br />
  Comparing this with our app's "index.html", the problem's obvious:</p>
<pre class="brush: html">
&lt;!DOCTYPE html&gt;

&lt;html&gt;

  &lt;head&gt;
&nbsp;   &lt;meta charset='utf-8'&gt;
&nbsp;   &lt;script src="http://open.mapquestapi.com/sdk/js/v7.0.s/mqa.toolkit.js"&gt;&lt;/script&gt;
&nbsp;   &lt;script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/jquery/1.6.2/jquery.min.js"&gt;&lt;/script&gt;

  &lt;/head&gt;

  &lt;body&gt;
&nbsp;   &lt;button id ="where-am-i"&gt;Where am I?&lt;/button&gt;
&nbsp;   &lt;div id="map"&gt;&lt;/div&gt;
&nbsp;   &lt;script src="scripts/whereami.js"&gt;&lt;/script&gt;
&nbsp;   &lt;link media="all" href="style/style.css" type="text/css" rel="stylesheet"&gt;
  &lt;/body&gt;

&lt;/html&gt;</pre>
<p><br />
  In the HTML, the button is assigned an ID of "where-am-i", but in the JavaScript, we're trying to use "whereami". So let's fix that:</p>
<pre class="brush: js">
var whereami = document.getElementById('where-am-i');

whereami.onclick = function() {
&nbsp; navigator.geolocation.getCurrentPosition(getMap, error);
};</pre>
<p>Now the app starts up without any errors, but when we click the button, the map doesn't appear, and we get a new message in the console:</p>
<p><img alt="" src="https://mdn.mozillademos.org/files/5203/error-console-geo-error-message.png" style="width: 720px; height: 560px;" /></p>
<p>This message is logged by our "whereami.js" script, and indicates that the geolocation API has returned an error - but it unhelpfully doesn't tell us what the error was. We can use the JavaScript Debugger to figure that out.</p>
<h3 id="Using_the_JavaScript_Debugger"><a name="Using-the-JavaScript-Debugger">Using the JavaScript Debugger</a></h3>
<div class="note">
  <p><strong>If you haven't followed along from the start of this walkthrough:</strong></p>
  <p>In this section we'll debug a very simple (but very buggy!) web app using the <a href="https://developer.mozilla.org/en-US/docs/Tools/Firefox_OS_Simulator" title="/en-US/docs/Tools/Firefox_OS_Simulator">Firefox OS Simulator</a>. The various versions of the app are in the <a href="https://github.com/wbamberg/firefoxos-simulator-walkthrough" title="https://github.com/wbamberg/firefoxos-simulator-walkthrough">firefoxos-simulator-walkthrough</a> repository on GitHub, and you can pick the walkthrough up at this point by starting with the <a href="https://github.com/wbamberg/firefoxos-simulator-walkthrough/tree/master/whereami-3" title="https://github.com/wbamberg/firefoxos-simulator-walkthrough/tree/master/whereami-1">whereami-3 </a>version.</p>
  <p>The app displays a single button labeled "Where am I?". When the user clicks the button, the app fetches the user's current location using the Geolocation API, and displays it on a map.</p>
  <p>But in this version, when we click the button the Geolocation API returns an error. In this section of the walkthrough, we'll use the JavaScript Debugger to figure out exactly which error is returned.</p>
  <p>The walkthrough assumes that you've <a href="/en-US/docs/Tools/Firefox_OS_Simulator#Installing_the_Simulator_add-on" title="/en-US/docs/Tools/Firefox_OS_Simulator#Installing_the_Simulator_add-on">installed the Simulator</a>, opened the Dashboard, and added the app by clicking "Add Directory" in the Dashboard, then selecting the app's "manifest.webapp" file.</p>
</div>
<p>In the Dashboard, click the "Connect" button:</p>
<p><img alt="" src="https://mdn.mozillademos.org/files/5197/dashboard-connect-button.png" style="width: 791px; height: 634px;" /><br />
  Then click "Connect" in the new page that appears, then select "chrome://prosthesis/content/shell.xul" in the next page. You should see the developer tools window:</p>
<p><img alt="" src="https://mdn.mozillademos.org/files/5199/dev-tools-console.png" style="width: 985px; height: 325px;" /><br />
  Click "Debugger", and you'll see the app's script:</p>
<p><img alt="" src="https://mdn.mozillademos.org/files/5201/dev-tools-debugger.png" style="width: 985px; height: 325px;" /><br />
  According to the <a href="/en-US/docs/DOM/window.navigator.geolocation.getCurrentPosition#PositionError" title="/en-US/docs/DOM/window.navigator.geolocation.getCurrentPosition#PositionError">Geolocation API reference</a>, the specific error is given by the <code>code</code> property of the <code>error</code> object that's passed into the error handler <code>error()</code>. So set a breakpoint inside <code>error()</code> by clicking to the left of line 8:</p>
<p><img alt="" src="https://mdn.mozillademos.org/files/5191/breakpoint-set.png" style="width: 985px; height: 325px;" />In the app, click "Where am I?". Execution should stop at the breakpoint:</p>
<p><img alt="" src="https://mdn.mozillademos.org/files/5189/breakpoint-hit.png" style="width: 985px; height: 325px;" /><br />
  Click where it says "Add watch expression" and type "error.code", and you'll immediately see its value, "1":</p>
<p><img alt="" src="https://mdn.mozillademos.org/files/5193/breakpoint-watch.png" style="width: 985px; height: 325px;" /><br />
  According to the <a href="/en-US/docs/DOM/window.navigator.geolocation.getCurrentPosition#PositionError" title="/en-US/docs/DOM/window.navigator.geolocation.getCurrentPosition#PositionError">Geolocation API documentation</a>, "1" means "Permission denied". This is an error web apps get if they have not requested the <a href="/en-US/docs/Apps/App_permissions" title="/en-US/docs/Apps/App_permissions">geolocation permission</a>, or if the permission wasn't granted by the user.<br />
  <br />
  Looking at the "manifest.webapp" file, we'll see that we didn't ask for the permission:</p>
<pre>
{
&nbsp; "name": "Where am I?",
&nbsp; "description": "A simple web app",
&nbsp; "launch_path": "/index.html",
&nbsp; "icons": {
&nbsp;&nbsp;&nbsp; "128": "/style/icons/earth.png"
&nbsp; }
}</pre>
<p><br />
  Let's fix that:</p>
<pre>
{
&nbsp; "name": "Where am I?",
&nbsp; "description": "A simple web app",
&nbsp; "launch_path": "/index.html",
&nbsp; "icons": {
&nbsp;&nbsp;&nbsp; "128": "/style/icons/earth.png"
&nbsp; },
&nbsp; "permissions": {
&nbsp;&nbsp;&nbsp; "geolocation": {
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; "description": "Needed to tell the user where they are"
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; }
&nbsp; }
}</pre>
<p><br />
  Save "manifest.webapp", and click "Update" in the Dashboard one more time. This time the app runs, and when you click "Where am I?" it asks you to share your location, and if you allow it, the app displays the map:</p>
<p><img alt="" src="https://mdn.mozillademos.org/files/5211/whereami-map.png" style="width: 400px; height: 606px;" /></p>
Revert to this revision