Welcome to Episode 3 of the Firefox OS Tutorial. This series will take you through the steps to writing Firefox OS Apps. This episode is about digging deeper into the Firefox OS Simulator and learning how to debug Firefox OS Apps.
- You have setup your machine with the Firefox OS Simulator. If not, you can check out Episode 1, which takes you through the entire setup.
- You have installed the IndiaPincodes Application that we covered in Episode 2. This tutorial uses that as an example but if you have any other application installed in the Firefox OS Dashboard inside of your Firefox Browser, then you should be able to follow along. But I strongly suggest getting the IndiaPincodes application source code from Github, installing as discussed in Episode 2.
What we shall cover in this Episode
- Starting / Stopping the Simulator
- Adding an application, Removing an application
- Observing Manifest errors
- Refreshing an Application
- Using Firefox Dev Tools to view console output
- Debugging your Firefox OS App
All the above steps will assume that you have installed an App (most likely the IndiaPincodes App if you have been following along) and that you have launched the Firefox OS Simulator from Web Developer -> Firefox OS Simulator in your Firefox browser. Off we go …
Starting/Stopping the Emulator
This is straightforward and you see a Stopped or Running toggle button on the left side as shown below:
Simple toggle to start or stop. When you switch to Running, the OS Simulator will launch. On Stopping, it will close down.
Adding/Removing an Application
As we discussed in the earlier episode, if you want to install a packaged app on the Firefox OS Simulator, you need to click on the Add Directory button as shown in the Dashboard below. This will bring up the File Selection dialog, where you can select the manifest.webapp file and the add-on will do the rest i.e. it will validate the manifest file, resources and when the Validation Result is ok, it will install the app. After successful installation, it will also start the application on your OS Simulator.
If you want to remove an application, you will find a X icon next to each application as shown in the screenshot below. Simply click that and your application should get removed. I have seen the result not reflecting (refreshing) accurately on delete in the Dashboard. But be ready for some surprises like that and simply refresh the browser page, the application should go away i.e. it has been uninstalled.
Observing Manifest Errors
The manifest.webapp file as we have learnt so far is the single most important file for your web application. It contains meta information about your application and is used by the OS to learn about the app, its permissions, the different icons and the launch URL. There are mandatory and optional elements and the OS Simulator does a good check of determining if you have missed out something. And if you have, it throws back the errors at you right in the Dashboard at the time of Adding or Refreshing the application.
Try out the following. Open up your manifest.webapp file in the editor and remove the name element. Try to Add or Refresh the element and you should see the Simulator not being too happy with you have done. It will throw back a validation message. A sample screenshot of the error is shown below:
So get used to manifest errors. It is normal to make mistakes here since you might most likely be using a text editor to type in things. Errors could range from XML validation errors to missing out of mandatory parameters, etc.
Correcting the errors is as simple as rectifying the mistakes in your manifest.webapp file and then refreshing the App. It is as simple as that.
Refreshing an Application
A normal development cycle will involve incremental development. You will develop a screen or functionality, see it work within the simulator and move on to the next one and so on. You need a quick way or refreshing or reloading your application into the OS Simulator. It couldn’t be easier with the Firefox OS Simulator. All you need to do is make your changes with your development tools as you have been doing and then come to the Firefox OS Simulator Dashboard and click on the Refresh button for the application.
The Simulator will reload and relaunch your application in the Emulator. Of course it will do the manifest.webapp validation for you before it reloads your new version.
Using Firefox Dev Tools
When was the last time that you wrote an application that did not have errors or did not involve debugging ? Never … correct ? It is time that you get familiar with the Developer Tools that are shipped within the Firefox Browser itself. While going into the details of the Developer Tools and every single feature might require an entire book, it is suffice to cover it briefly here so that at the very least, you can start putting in console or logging statements to understand and help you debug what could be going on in the application. The developer tools can also be used to do things like monitor the network traffic, see the HTTP request/ response, change styles for the HTML Elements and much more.
To open up the Developer Tools for your particular Firefox OS Application, all you need to do is click on the Connect button for each application as shown below. In this case we are doing it for the IndiaPincodes application that I have in my Dashboard:
When you click on Connect, it will open up the Dev Tools window in your browser as shown below and will output the message onto the Console window that it has connected to your IndiaPincodes App. By that what it means is that you can now monitor all the stuff happening inside your application from the Dev Tools window itself, including debugging that we shall see in the next section.
The screenshot of a successful Connect is shown below:
Now, when we run the application in the OS Simulator i.e. enter a few pincodes and get the result, you will see that network calls are traced. Additionally any console.log statements that you would have used in your code (and which we did for printing out the result) will be seen in the output too. This is very useful for understanding what is happening at different stages in your application.
You will notice from the screenshot below that it also shows the line number of the file (index.html:24) which had in the console.log statement in your code. If you click on the hyperlink of the filename:linenumber, it will even open up your code at that exact point.
For more information on Dev Tools, visit Developer Tools note on the Mozilla Developer Network.
Debugging a Firefox OS App
Now comes the interesting part. We shall see how to use Developer Tools to help debug the application. By debugging an application, we mean not just putting console.log statements but breakpoints and single-stepping through your code line by line. Just like you would in any other Developer IDE (Integrated Development Environment).
Follow the steps below patiently. We will assume that you have launched the IndianPincodesApp locally and it has come up with its first screen on the OS Simulator.
Make sure you have Connected to your Firefox OS App as explained in the earlier section. Go to the Debugger tab as shown below:
You shall see that the index.html page is highlighted and the source code is visible in the pane to the right. What we are going to do now is to put a breakpoint in some section of our code. We shall put the breakpoint right at the point where we receive the response from our call to the public API. Fair enough?
On the right side of the pane, where you see the code, scroll down a bit till you come to the section as shown below:
Go ahead and tap in the gutter near line #20. When you tap on it a blue circular icon should appear, which means that the breakpoint is set. If you tap again on that, it will toggle and the breakpoint will be cleared. Just like any other Debugging environment that you have worked with.
Once again, just for the sake of repeating, we have put the breakpoint on line #20, which is invoked when we receive the result from the Ajax call to the Pincode API.
Now, switch over to your OS Simulator, which is running the Pincode App and enter the Pincode 400001 (a valid India Pincode) as shown below. Click on the Search button.
You will notice that the Application execution will halt at the breakpoint after a successful call to the public API. Switch over to your Dev Tools view and you will see the application execution waiting for you as shown below:
On the right side you can view your current object and inspect many other standard window and Global parameters. Now comes the fun part. Let us say that we want to monitor the obj object as the call happens. Remember the execution has stopped here for the moment and the data has come in.
Go to the Add watch expression area that you see on the top right in the Dev Tools window. The screenshot is shown below and enter the variable name obj and press Enter.
If you see some error stating that it could be evaluated, that is a correct message since the particular line of code that initializes the obj variable has not yet been executed. Now let us move ahead in the execution.
Click on the Step Over button as shown above. You will find that the obj object gets populated in our Watch expression with the values.
Let us move ahead and let the rest of the application execute. To do that, click on the Run button as shown below:
This will move forward with the rest of execution and we will see our application update its results list as seen in the simulator screenshot below:
I encourage you try out debugging because it will be needed as you progress along in your Firefox Apps. Put in some breakpoints, single step through the code, inspect some variables, etc.
Coming up Next
The next episode cover Firefox Marketplace and the steps to submitting and publishing your Firefox OS Application.
Complete Firefox OS Tutorial
- Episode 1 : Setting up your Development Environment
- Episode 2 : Hello World
- Episode 3 : Working with the OS Simulator
- Episode 4 : Submitting your Application to the Firefox Marketplace
- Episode 5 : Location, Location, Location
- Episode 6 : Enabling Storage
- Episode 7 : Storage using IndexedDB
- Episode 8 : Using Web Activities
- Episode 9 : Device Storage
- Episode 10 : Using mBaaS
I would love to hear your feedback on the series so far. Do put your feedback in the comments. If you are facing issues, use the comments to let me know about it, I will do my best to answer your queries. And by putting in your issues within this thread itself, it will help build collective knowledge that could help other readers.