Firefox OS Tutorial : Episode 2 : Hello World

Welcome to Episode 2 of the Firefox OS Tutorial. This series will take you through the steps to writing Firefox OS Apps. This episode is about writing our first Hello World program on Firefox OS.

Prerequisites

  • 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.

Brief Overview of Firefox OS Apps

Firefox OS supports 2 kinds of applications : Hosted Apps and Packaged Apps.

Hosted Apps are those that are hosted at a web url. All the files that compose the app i.e. HTML, JS, CSS, images, etc are all present at the hosted url itself. No file is present on the device and the device will need to be connected to the internet to use it. There are mechanisms now in HTML5 like AppCache that allow you to cache assets of the file locally though for most purposes, we will assume that hosted apps are completely present online.

The advantage of hosted apps is that you can update them easily and all your users will get the latest version immediately on next access. The flip side is that they have to be connected.

Packaged Apps take the opposite approach. All the files that compose your web app i.e. HTML, JS, CSS, images, etc are packaged into a ZIP file. The ZIP file is downloaded on your device and the app is installed locally. Applications that are deployed in this fashion can function without the device being connected to the internet. However, if your application makes use of some public API or external web service, you will need to be connected.

The Firefox Marketplace which we shall we in a later episode supports listing of both Hosted and Packaged Applications.

Episode 2 in Action

Let us check out the application in action first. This will help you understand what we shall be achieving by the end of this blog post. While we follow tradition and would like to say “Hello World”, it will be good to go a bit beyond that.

What we shall write is a mobile application that will give us details on the different Pincodes in India. Pincodes are similar to Zipcodes if you want an analogy. You enter a valid Pincode in the application and it will give you the details of that Pincode i.e. its State name, District Name, etc.

The mobile application makes use of an external Web service called India Pincodes. This will also help demonstrate making Ajax calls over the network from your Firefox OS Mobile. Nothing special there but by taking a little more realistic example, it will help set off things on the right note.

All right then, the first screen of the mobile app is shown below:

app1

When we enter a valid pincode e.g. 110001, the app makes a call to the Pincode service and retrieves/parses/displays the information as shown below:

app2

Simple and useful ? Let’s get going with the code. Note that the example screenshots are from the Firefox OS Simulator running locally.

Download Full Source Code – Episode 2

I suggest that you begin with a full download of the project source code. Since the project depends on libraries like jQuery and jQuery Mobile, it will save you the hassle of downloading the dependent libraries.

Go ahead & download the code from : https://github.com/rominirani/IndiaPincodesApp

Extract all the code in some folder. For e.g. on my machine, the code is present in e:\firefox-os-blog\episode2\IndiaPincodesApp but it could be any directory of your choice. You should see a folder structure inside of IndiaPincodesApp, that looks something like this:

folder-structure

You will notice that jQuery and jQueryMobile libraries are present but the key files that make up your application are index.html and the manifest.webapp file that we shall discuss next.

The code – index.html

Since our application is a simple single screen application, all we need at this point is a single index.html file. The code for the same is shown below:

Let us divide the discussion into 2 parts: the UI and the functionality.

The UI is based on jQuery Mobile, which is a responsive web UI framework. I strongly suggest to use UI frameworks that are responsive in nature i.e. they adapt to different screen sizes and resolutions. Increasingly the web is being accessed by people with different screen sizes and resolutions and it is imperative that your web UI adjust itself gracefully for optimum web display. You can also choose to go for frameworks like Twitter Bootstrap or even Firefox UI building blocks, but I leave that choice to you.

One point to note here: One may argue about why a simple application like this needs heavy frameworks like jQuery and jQuery Mobile. Can’t we just get going with our plain simple HTML coded by hand. Yes you can. My intention here is not to demonstrate optimum coding techniques but to show you that you can use your existing frameworks while coding Firefox OS apps. The idea is to indicate to the reader that all the tools/frameworks that he/she is used to should be used as needed.

So moving on to the UI part, focus on lines 40-55 for the user interface.

  • Line 47 declares the input field that we shall use to allow for the user to enter the pincode. Note that we make good use of HTML5 attributes like placeholder and autofocus. The placeholder attribute is a good way to specify what needs to be entered in the input (like a hint). It saves a lot of real estate on a small mobile screen.
  • Do note that the inputtype is also specified as search. This is a very useful attribute on mobile screens. It will allow for a quick way to clear up the input as you type text.
  • If you want to brush up on HTML Form Features and input types, check out my posts: New Features in HTML5 Forms and New Input Types.
  • Line 48 specifies a button labeled Search, which when clicked needs to retrieve for us the details of the Pincode entered.
  • Line 50-52 define the results div where we shall display the results. This is just my way of definining the UI. Feel free to be as creative as you want.

Let us discuss the functionality now. For this, focus on lines 11-34:

  • We are using the standard jQuery ready callback to do our wiring once the page is loaded.
  • The only functionality that we need is a click handler for the btnSearch button. The code is a straightforward Ajax call to the web service hosted at http://pin-codes.in/api/pincode/<YourPinCode&gt;. This service returns us a JSON formatted string for the Pincode that we enter. For e.g. if you make the following request http://pin-codes.in/api/pincode/400001, it will return you the Pincode details for pincode have a value 400001.A sample response is shown below:
    {
    status: “SUCCESS”,
    PostOffice: “Town Hall Po”,
    District: “Mumbai”,
    State: “Maharashtra”
    }
  • A key thing to note over here. You could utilize the jQuery ajax methods but I have intentionally shown you the raw XMLHTTPRequest object over here, so that you are aware of what is going on at the ground level. However, pay attention to line #16. The XMLLHttpRequest object is instantiated in the normal way but with an additional setting of mozSystem:true as shown below. This is required for the Firefox OS browser. I could not get it to work without that.

    var xhr = new XMLHttpRequest({mozSystem: true});

  • The next few lines make the standard Ajax call to the service and when the response is ready, it parses out the information, creates individual li elements for the result data and populates the searchResults with the response.

That is all we have in the code.

Manifest file – manifest.webapp

Now that the code is ready, we need to specify an additional file known as manifest.webapp. This file is needed to provide various meta data about your application. If you are coming from an Android world, think of this file as the android-manifest.xml file that you write.

We shall go into the details on manifest in a later episode but for now, it is sufficient to know that this file will provide information like:

  • Name of your App
  • App Version
  • App Description
  • App Icons
  • Permissions that your app needs to run on device
  • Locales that your App supports
  • and much more

Take a look at the manifest.webapp gist shown below:

Let us discuss the entries:

  • The version, name and description should be straightforward to understand. A good practice is to choose them carefully so that they reflect accurately what your application does. Choose a versioning scheme that reflects your internal schemes and/or development/build processes.
  • The launch_path specifies what file is to be invoked when your app is launched. This is ideally the first page that you would like to show when the user launches your app. The value should be a relative path in your application directory. In our case, the file we want to launch on application start is index.html and since the manifest.webapp file is in the same folder as the index.html, so we simply specify the value as /index.html. But make it a relative path in case the first page is nested inside some other directory than where the manifest.webapp is present.
  • When your mobile application is installed on the Firefox OS Device, the OS will select the icon to be shown on the device, which when tapped will launch your application. It is important that you specify icons of different sizes that show up well. For e.g. provide 16,32,48,128 pixel icons. Note that 16 means an icon or sie 16×16 pixels. I have found a nice utility on the internet : http://icon-generator.net/ that is good enough to generate the icons with the right sizes for you. Note that for submission to Firefox OS, you will need to submit a 60×60 icon. Check out the Firefox OS Icons Style Guide.
  • The next values developer, url and name specify details on who created the application. Be consistent with these values and do specify a url that actually exists :-)
  • The default_locale is English (en) for now.
  • The next 2 values are critical to the functioning of this application. This is because our application needs to invoke some special APIs i.e. in our case it is the Ajax call that is made to the external web service. Hence we have to specify one property name type and its value is set to privileged. Only privileged apps have access to special Web APIs for e.g. some of the device APIs, which we shall be seeing later. It is good to have this setup now itself. And since we have mentioned that our application type is privileged, we have to also mention which permissions you need. And that is specified by the permissions parameter. Currently since we need just the XMLHttpRequest to be made, we specify this as follows:
    “permissions”: {
           “systemXHR”: { “description”: “Required to make Ajax Calls over the Network” }
    }

    There is a full list of permissions for your reference. For a discussion on different types of Firefox Apps, check this developer note.

Local Installation and Testing

This completes our discussion of writing our first Firefox OS App. Now comes the part of seeing it actually work. All we need to test out this application is:

  1. You should have installed the Firefox OS Simulator add-on in your Firefox Browser.
  2. A working internet connection from your machine.
  3. You should have downloaded/written the application as described above. We will assume that the index.html and manifest.webapp file are present in a folder named IndiaPincodes. You should navigate to your own directory structure when called to later.

Steps to install the application in your Firefox OS Simulator are given below:

  1. Launch your Firefox Browser. Next, launch the Firefox OS Simulator from Web Developer -> Firefox OS Simulator. This will launch the Firefox OS Simulator Dashboard screen as shown below:
    dashboard1
  2. Since we have written a packaged app, we need to specify to the Simulator where our manifest.webapp file is. That will be sufficient for it to pick up the rest of the details including the launch URL and so on. Click on the Add Directory button as shown below:dashboard4
  3. This will bring up a file dialog where you should navigate to your IndiaPincodes directory and select the manifest.webapp file as shown below:
    manifest-sel
  4. Firefox OS simulator will then read the manifest, validate it and if all is well install the app on the Simulator for you. You should see a successful validation message as shown below. This will indicate that all is good and your application is setup and installed.
    dashboard2
  5. It will also launch your application for you in the Firefox OS Simulator and you can validate that your app functions correctly. Use a few pincodes like 400001, 400002, 400101. If you give an invalid pincode it will show the value as undefined. Keep in mind that I have not tried to code out every validation or proper error message. My intention is to get you started with Firefox OS development so I leave it to the user to improve the code as an exercise. 
  6. Your application on successful install will now be available in the Firefox OS Simulator as shown below. Even across Firefox OS Restarts, this will be available.ff-installed

Development Cycle

In case you want to make changes to your application, all you need to do is modify the index.html or manifest.webapp or additional files in your application. You do this in a normal way on your machine.

Once the changes are ready, you can simply go to the Firefox OS Simulator and click on Refresh button that you see next to your application. This will load the latest version of the application and it will even launch the application for you in the OS Simulator. Nice … isn’t it ? 

dashboard3

Next Steps

I encourage you to enhance the current application by providing error checks, validation,etc. If you want, you could possibly try out writing your own app. If you are looking for other public web apis to call, take a look at ProgrammableWeb, they list thousands of APIs. Maybe you could write a Weather App, Currency App .. the world is yours.

Coming up Next

The next episode will go into a little more detail for the Firefox OS Simulator, some issues that you may see when you write incorrect manifest.webapp and how to use the Dev Tools within Firefox to understand issues, logs, etc.

Once we cover that, we shall get going with publishing the application to the Marketplace in later episode.

Complete Firefox OS Tutorial

Feedback

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.


Firefox OS

About these ads

21 thoughts on “Firefox OS Tutorial : Episode 2 : Hello World

  1. Very interesting article.
    I’ve a question about Firefox OS security model about app data and app source code. You said i can sell my application but how i can hide app source code?
    My app download sensible data from internet, is there a way to store it in unaccessible way from outside?
    Last question about platform services: Android, for example, offer a lot of services to share data cross app (think about Content Provider, Broadcast event, widget,…), are there similar mechanims on FirefoxOS?

    Thank you.

    1. Thank you for your feedback on the article.

      Your questions are great and I am not an expert to have definite view on those but I will give my views. Both your questions are more general in nature and not too specific about Firefox OS. I believe your questions fall under the Web Development Technologies a such.

      1. Standard encryption techniques should apply to your sensitive data. Also it is a good practice not to store too much sensitive data on the device and even if you have do, it could be encrypted in some way or you keep an indirect reference which can then be fetched from the server side using that reference.

      2. About Viewing the Source code, people have been going for obfuscating the source code in some way or the other. I am not too sure if you can fully control all aspects of it. Here is a discussion : http://www.htmlgoodies.com/beyond/article.php/3875651/Web-Developer-Class-How-to-Hide-your-Source-Code.htm

      3. About Platform Services, you are right about the different features that Android provides like CP, Broadcast receivers, etc. I would say that is Android’s programming model and the set of classes/modules to interact with the OS and build applications. Firefox OS programming model is built on Open Web Standards and I do not believe that they will provide any rigid programming services like that but instead they will leave it open to the developers to use whatever framework they like. For e.g. you can use Angular JS in your Firefox OS app to enforce some sort of structure to your code and introduce things like services, factories, singletons in your code. So it is pretty much open that way.

      Hope this helps.

  2. Hello rominirani,

    great articles so far! Where I’m stuck at the moment is to provide a unique look to the app so that it Looks like a real Firefox App. I already discovered the site Building-Blocks-gh-pages with the specific Firefox css-Styles but there is no example for e.g. page transitions.
    By the way it would be great to have more examples in code for complete apps. Maybe a sample app with Multi pages and a master/Detail view. Do you know if These examples exist anywhere? I really want to use the Firefox-Style so I don’t want to use jQuery Mobile right now.

    1. Thanks for the feedback.

      I agree with you that jQuery Mobile is not probably the right choice and you might end up using only a function or two from jQM and end up linking the entire library. Plus your point about a Firefox-Style is a valid one too.

      I suggest that you could look at Firefox Building Block : http://buildingfirefoxos.com/building-blocks/action-menu.html. For CSS Styles / transitions – have you looked at : http://buildingfirefoxos.com/transitions ?

    1. I have been having problems with the particular service i.e. Pin Code Service. Sometimes it works and at times it does not. I guess that is the price we pay for public Web Services, which might not be reliable. I would suggest that you should try out the sample with any other public service for more consistency and reliability.

      1. Hi ,
        I have the same problem for the pin code app … though I have modified it a little bit such that works in IE8 .But in Firefox when i click search nothing is displayed in the unordered list .Is this due to the cross domain api request AJAX makes with this app?? I found mozilla blocks any such request,if this is true then is there any work around for this to access cross domain api in FF??Other wise this app will not work in OS :(

  3. Hello.

    I followed the tutorial and it’s great, then I got some problem with another Webservice, my code:

    $(document).ready(function(){
    $(“#btnSearch”).click(function(){
    pincode=$(“#searchCriteria”).val();
    var xhr=new XMLHttpRequest({mozSystem: true});
    xhr.open(“GET”,”http://api.geonames.org/postalCodeLookupJSON?postalcode=” + pincode + “&country=MX&username=demo”,true);
    xhr.onreadystatechange = function () {
    if (xhr.readyState==4) {
    obj=JSON.parse(xhr.responseText);
    result=”Ubicacion: ” + obj.placeName + “”;
    result+=”Estado: ” + obj.adminName1 + “”;
    result+=”Longitud: ” + ojb.lng + “”;
    console.log(result);
    $(“#searchResults”).html(result);
    $(‘#searchResults’).listview(‘refresh’);
    }
    }
    xhr.send();
    });
    });

    The Firefox log (in emulator) returns me:

    [01:32:11.013] ReferenceError: ojb is not defined

    Why happen this? Thanks a lot in advice.

    1. As long you have enabled the systemXHR permission for the app, things should be fine in making the call to the service. On your local desktop browser, the app is being served from your local file system and by security design in browser, I believe, the browser will block cross – domain requests.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s