Developing Apps for Firefox OS

8/14/2019 Developing Apps for Firefox OS

1/44


2/44

Developing Apps for Firefox OS

Concepts, Techniques and Practical Solutions

Michael Romer

This book is for sale athttp://leanpub.com/firefox-os

This version was published on 2013-08-15

This is aLeanpubbook. Leanpub empowers authors and publishers with the Lean Publishing

process.Lean Publishingis the act of publishing an in-progress ebook using lightweight tools andmany iterations to get reader feedback, pivot until you have the right book and build traction onceyou do.

2013 by Michael Romer, Grevingstrasse 35, 48151 Mnster, Germany, [email protected] -All rights reserved.
http://leanpub.com/manifestohttp://leanpub.com/http://leanpub.com/firefox-os


3/44

Also ByMichael RomerWebentwicklung mit Zend Framework 2

Web Development with Zend Framework 2

Persistenz in PHP mit Doctrine 2 ORM

PHP Data Persistence with Doctrine 2 ORM
http://leanpub.com/doctrine2-enhttp://leanpub.com/doctrine2http://leanpub.com/zendframework2-enhttp://leanpub.com/zendframework2http://leanpub.com/u/michaelromer


4/44

Contents

1 Introduction (available) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11.1 Firefox OS at a glance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11.2 Open Web Apps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21.3 Web Runtime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21.4 Firefox Marketplace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

1.5 WebAPIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31.6 Web Activities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31.7 Firefox OS Boilerplate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

2 A basic development environment (available) . . . . . . . . . . . . . . . . . . . . . . . 42.1 The browser now is the mobile apps developers best friend . . . . . . . . . . . . . . 42.2 Firefox OS Simulator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42.3 Firefox OS hardware devices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42.4 Mortar & FxOSstub . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

3 Hello, Firefox OS! (available) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

3.1 Building the first app . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63.2 Firefox OS architecture: Gonk, Gecko & Gaia . . . . . . . . . . . . . . . . . . . . . . 83.3 Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

4 The Manifest file (available) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114.1 Meta information about an app . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114.2 App settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124.3 Developer settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144.4 Permission settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

5 WebAPIs by example (partly available) . . . . . . . . . . . . . . . . . . . . . . . . . . . 165.1 The Grumpy Phone app (using Vibration API & Proximity API) . . . . . . . . . . . . 165.2 More Web APIs (TODO) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

6 Web Activities by example (partly available) . . . . . . . . . . . . . . . . . . . . . . . . 256.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256.2 The Funny Faces app (Pick Activity) . . . . . . . . . . . . . . . . . . . . . . . . . . . 256.3 More Web Activities (TODO) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31


5/44

CONTENTS

7 Programming the Firefox OS Web Runtime (partly available) . . . . . . . . . . . . . . 327.1 HTML & CSS (TODO) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327.2 JavaScript (partly available) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327.3 Firefox UI Build Blocks & Transitions (partly available) . . . . . . . . . . . . . . . . 34

7.4 Single Page Apps (partly available) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357.5 HTML5 canvas (TODO) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 367.6 Working offline (TODO) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 367.7 jQuery Mobile UI framework (TODO) . . . . . . . . . . . . . . . . . . . . . . . . . . 367.8 WebGL (TODO) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

8 Distributing apps (partly available) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378.1 Introduction (TODO) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378.2 Distributing via a website (TODO) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378.3 Submitting to a Marketplace (available) . . . . . . . . . . . . . . . . . . . . . . . . . 378.4 App updates on a Marketplace (available) . . . . . . . . . . . . . . . . . . . . . . . . 38

9 Modifying the Firefox OS core UI Gaia (TODO) . . . . . . . . . . . . . . . . . . . . . . 39


6/44

1 Introduction (available)We live in crazy times. Not long ago everybody moved to the Web mainly for its killer feature toeasily access applications-no downloads, no installs, no updates, no hassle. People more and moremoved away from native Windows or Mac applications and into the browser using apps runningonline directly in the browser. They did so on their PCs and laptops, but then Apple came withits iPhone and later the iPad. Surprisingly, with the iPhone and iPad, locally installed apps had avery successful comeback. Its hard to tell why exactly this happened, but there are definitely goodreasons, e.g.:

Apple opened up its App Store with a payment system built-in. In fact, the Web still lacksof a standard solution to make it as easy as in an app store to pay for media or applications.In fact, with a typicall app store, it couldnt be much easier anymore to buy digital products.This is the main reason for publishers and developers to hop onto the native apps wave-theycan easily monetize their digital products.

New apps can be discovered easily using the App Store.

Its easy to launch an app (via a home screen icon) and to switch between running apps.

Native apps mostly offer great usability and feel snappy. They are built from the ground upfor the touch interfaces of smartphones and tablets.

Apps can do things which web apps cannot. Mainly because web apps running in a browserare not allowed or simply technically cannot access important device features such as camera,proximity sensor and the like.

Push notifications offer a great way to receive messages from the web in a convenient shortmessage (SMS) fashion.

Native apps mainly always still work well while being offline.

And lastly: Apps are en-vogue.

However, in fact, there is no reason why an app needs to be built with proprietary technology. WithFirefox OS, Mozilla now brings open web technologies to mobile app development, challengingproprietary platforms from Apple (iOS) or Google (Android). Firefox OS essentially is completelybased on open standards and is a new competitor to the established mobile platforms. If one believes

in the web, Firefox OS is an interesting new mobile platform which huge potential.

1.1 Firefox OS at a glance

On first sight, Firefox OS looks like just another operating system for mobile phones. However, whatit makes special is that its apps are developed using standard web technologies like HTML5, CSS and


7/44

Introduction (available) 2

JavaScript. Mozilla, the creator of the famous Firefox browser-and now also of Firefox OS-calls thesekinds of apps Open Web Apps. This is a fundamentally different approach compared to Apple withiOS and Objectiv-C or Google with Android and Java.

1.2 Open Web Apps

Open Web Apps come in two different flavors: Hosted apps and packaged apps. While hosted appsrun on a server on the web, packages apps bring all the apps code with them in an installer-likefashion. Obviously, both types have its pros and cons, but by definition, both types are real FirefoxOS apps.

1.3 Web Runtime

Open Web Apps run in a so-called Web Runtime. A Web Runtime essentially is a browser-likeruntime environment for web apps while the browser itself is invisible during execution-no typicalbrowser frame, toolbar, etc. One may remember Mozilla Prismand Adobe Air-both conceptuallyweb runtimes as well. Prism is not an active project anymore. A web runtime to power open webapps is available in Firefox OS, but also on Windows, Mac as well as Android.

1.3.1 Hosted apps

Hosted apps can simply be existing websites that also work well on small screen sizes and touchinterfaces. If an existing websites is built in a fluid manner, e.g. by using responsive web design

techniques, they may work on a Firefox OS mobile device as-is. This is especially true, if a websitealready has an app-like UI, e.g. if jQuery Mobile is used. Also with hosted apps, updating the appsimply means updating the website-the workflows are very much the same compared to regularweb site development.

On the flip side, hosted apps mostly dont work without Internet connection. Thanks to the HTML5Appcache Specification this issue can partly be solved elegantly, as we will see later in the book.A bit more painful is the fact, that hosted apps cannot access all the APIs offered by Firefox OS,meaning they cannot access several device features. The reason for this mainly is security, as hostedapps cannot fully be security cleared beforehand. This may or may not be an issue depending onthe application itself. Hosted apps are deployed on a remote server. The only component installed

locally on the mobile device is the apps Manifest.

1.3.2 Packaged apps

Packaged apps are much more like apps on Android or iOS as they are self-contained and dontneed a website running on a remote host to function. Of course, they may also consume remote

https://mozillalabs.com/en-US/prism/
https://mozillalabs.com/en-US/prism/https://mozillalabs.com/en-US/prism/


8/44

Introduction (available) 3

web services, however, this is not required. A packaged app works standalone by default, thereforeoften does not need constant Internet connectivity. As packaged apps can be reviewed for securityissues beforehand, they may access more APIs compared to hosted apps. This makes packaged appsparticular interesting.

As with hosted apps, there is a flip side. Packaged app updates must be distributed to all deviceswith the app installed. This, obviously, is harder than updating a website.

Technically, a packaged app simply is a zip file with some additional metadata. This means, apackaged app is installed completely on the device with its code and assets as well the Manifestfile.

1.4 Firefox Marketplace

The Firefox Marketplace is a place get new apps for a Firefox OS device. By design, there might beother stores distributing Firefox Apps, very much like in the Android ecosystem while Apple runsthe one and only store for iOS App downloads.

1.5 WebAPIs

WebAPIs mainly allow for a closer hardware integration. They let open web apps access devicefeatures, very much like Apple exposes certain feature through their native APIs. WebAPIs areconsumed by web technology, e.g. by JavaScript. WebAPIs connect the web with the mobile devicehardware features.

1.6 Web Activities

Web Activities let web apps to work together. Web apps may state to be able to handle a specific userintent and other apps may rely on them to get the job done without providing a solution themselves.If more than one other web app declared to handle a certain action, the user is prompted to choosethe app he wants.

1.7 Firefox OS Boilerplate

Firefox OS Boilerplateis a demo app. It shows how to integrate an install button as well as it usessome WebAPIs and Web Activities. The easiest way to run Firefox OS Boilerplate is to point theFirefox OS Simulator to the URL http://robnyman.github.io/Firefox-OS-Boilerplate-App/. If youhave a Firefox OS based device available, you may use that as well.

https://github.com/robnyman/Firefox-OS-Boilerplate-Apphttp://robnyman.github.io/Firefox-OS-Boilerplate-App/
http://robnyman.github.io/Firefox-OS-Boilerplate-App/https://github.com/robnyman/Firefox-OS-Boilerplate-Apphttp://robnyman.github.io/Firefox-OS-Boilerplate-App/https://github.com/robnyman/Firefox-OS-Boilerplate-App


9/44

2 A basic development environment(available)

2.1 The browser now is the mobile apps developers

best friend

A major advantage of Firefox OS apps is the fact that they are mainly simple web apps that may berun in any browser available. Only if a web heavily relies on Firefox OS specific features exposedthrough WebAPIs or Web Activities, maybe more is needed than a simple web browser.

2.2 Firefox OS Simulator

Even though Firefox OS apps are entirely based on web technology and therefore can be run inmainly any normal web browser, they are more fun when run in Firefox OS Simulator, an add-onfor the famousFirefox browser. Once installed, you may launch apps from either a given URL ora local directory. The Firefox OS Simulator allows using certain WebAPIs provided by Firefox OS,e.g. Check battery. They wont work in other browsers. However, not all available WebAPIs willfunction in the simulator. The vibration feature, for instance, does not work. You will need to test ina real device, if you want to see this API in action.

2.3 Firefox OS hardware devices

Unfortunately, also the Firefox OS Simulator has its limitations. It does not yet simulate all the APIsavailable on a Firefox OS hardware device. So depending on the applications needs, the simulatormight not be enough. Also, when running the simulator on a non-touch device like a regular laptop,PC or Mac, one cannot interact which the app in the way one does on a real device. So mainly, atsome stage, depending on how serious one does develop for Firefox OS, owning a hardware device isactually a must. However, it is definitely not needed for the first steps. This makes starting developingfor Firefox OS cheap and convenient.

In fact, there are mainly three different ways of running a Firefox OS open web app while indevelopment:

Firefox Browser: Its a great way for modifying CSS, inspecting elements, and developing/de-bugging JS code.

http://www.mozilla.org/de/firefox/new/
http://www.mozilla.org/de/firefox/new/http://www.mozilla.org/de/firefox/new/


10/44

A basic development environment (available) 5

Firefox OS Simulator: A great way to run apps in a more target-like environment with accessto many device features such as Web APIs, however, not to all of them.

Firefox OS hardware device: The most native way to run an app with access to all of thedevices features, but with somewhat limited debugging possibilities.

However, there indeed is a forth option: A desktop build of Firefox OS (also known as B2G) whichwe will take a look at later in the process.

2.4 Mortar & FxOSstub

Mortar is a collection of app templates for different app types. Unlike Firefox OS Boilerplate, thetemplates serve as a starting point for your own app, if you begin coding your app from scratch. Asan alternative, there isFxOSstubwhich is even more simplistic.

https://github.com/Jaxo/fxosstub
https://github.com/Jaxo/fxosstubhttps://github.com/Jaxo/fxosstub


11/44

3 Hello, Firefox OS! (available)3.1 Building the first app

Lets quickly ramp up a first app. We will build a Twitter client that shows the latest tweets onMichael Jackson. First, we clone themortar-app-stub:

1 $ git clone https://github.com/mozilla/mortar-app-stub.git

You will need to havegitinstalled on your system before you can run this command. Open thecloned folder in your favorite IDE and change index.htmlto:

1

2

3

4

5

6

7

8

9

11

12

14

15

16

17

18

19 20 Twitter Client

21

22

23

https://github.com/mozilla/mortar-app-stubhttp://git-scm.com/
http://git-scm.com/https://github.com/mozilla/mortar-app-stubhttp://git-scm.com/https://github.com/mozilla/mortar-app-stub


12/44

Hello, Firefox OS! (available) 7

24

25

26

27

28

29

30

31

32

33

34

Next, openapp.jsin folder js and add the following on top:

1 $.getJSON("http://search.twitter.com/search.json?q=Michael+Jackson&callback=?", f\

2 unction(data)

3 {

4 $(data.results).each(function(i,v)

5 {

6 var tweet='' + this.text + '\

7 ';

8 $('#tweetlist').append(tweet);

9 })

10 });

Last but not least, lets add a custom icon to our app. A Firefox OS application icon may be given indifferent dimensions for different use cases. For the sake of simplicity, we add a 64px icononly. Wedownload the file and add it toimg/iconswith the filenametwitter-64.png. Add the following tomanifest.webappwhile replacing the existing file content:

1 {

2 "version": "0.1",

3 "name": "Twitter Demo Client",

4 "description": "Twitter Demo Client from Firefox OS book",

5 "launch_path": "/index.html",6 "icons": {

7 "64": "/img/icons/twitter-64.png"

8 },

9 "developer": {

10 "name": "Michael Romer",

https://assets.mozillalabs.com/Projects/Firefox%20OS/UX/VsD/v01.0/Icon%20App%20Templates/PNG/MozillaFXOSIconTemplate1.png
https://assets.mozillalabs.com/Projects/Firefox%20OS/UX/VsD/v01.0/Icon%20App%20Templates/PNG/MozillaFXOSIconTemplate1.pnghttps://assets.mozillalabs.com/Projects/Firefox%20OS/UX/VsD/v01.0/Icon%20App%20Templates/PNG/MozillaFXOSIconTemplate1.png


13/44


11 "url": "https://leanpub.com/firefox-os"

12 },

13 "installs_allowed_from": ["*"]

14 }

Now, head over to the Firefox browser and its Firefox OS Simulator add-on. Make sure the simulatoris running-there is a toggle switch on the side-and then pick the app directory from your local disk.Then click run and see the result (also notice the icon added to the home screen):

Firefox OS Simulator in action

Et voil-we just developed our first Firefox OS app. Sure, the world hasnt been waiting for this appand its benefits are limited, but it still is a fully function mobile app built in minutes and with onlystandard web technologies involved.

3.2 Firefox OS architecture: Gonk, Gecko & Gaia

Before we deep dive into the details of a Firefox OS app, lets take a quick look at the general FirefoxOS architecture. At its core, there is Linux. In conjunction with different open source libraries-handling I/O and other device features such as vibration-the infrastructure layer, called Gonk,


14/44


does all the bootstrapping and finally runs Gecko. Gecko essentially is the runtime environmentfor apps built with web technology. So its no surprise that Gecko is also already used by Firefox,Thunderbird as well as other browsers like Camino or Flock. Gecko paints graphics onto the screen,runs JavaScript, does networking, etc. In short, Gecko runs the apps. During the early alphas of

Firefox OS, the system was therefore known as B2G or Boot to Gecko-because the system simplyboots to Gecko.

And then there is the beautiful Gaia:

Gaia - The main UI of Firefox OS

Gaia is the main user interface. And, believe it or not, Gaia itself is a web app. So, whenever oneinteracts with its phone, one interacts with HTML5 web apps already. If one is interested in learningmore about the technical details of Gaia-the full source code is available to the world ongithub.

Lets get back to Gecko for a moment. Together with Gecko, a whole bunch of WebAPIs-some ofthem already standardized and known as a part of HTML5-provide access to device features. Geckoand the WebAPIs together form the so-called Open Web Platform that sits on top of Gonk, thelow-level infrastructure layer. Custom Firefox OS apps, as well as the main device UI itself, Gaia,utilize the Open Web Platform to function.

https://github.com/mozilla-b2g/gaia
https://github.com/mozilla-b2g/gaiahttps://github.com/mozilla-b2g/gaia


15/44


3.3 Security

Clearly, nobody wants to have an insecure mobile device in his or her pocket. As Firefox OS connects

a web app with the underlying hardware, there is the risk of malicious applications. Just image thatany web app out in the wild may access random data on ones mobile device. Therefore, Firefox OSemploys a multi-layered security model. In fact, all functions of a device that a web app such as Gaiaor any custom app wants to use, are made available by Gecko exclusively. There is no other way torequest access to device functions. So Gecko with its WebAPIs acts as the one and only gatekeeperand enforces security policies. For instance, there is no direct access to any files on the filesystemwithout going through Gecko and a WebAPI.

Not all apps can access all the WebAPIs available. In fact, Firefox OS knowns different trust levels:

Certified: Highly trusted system apps that have been approved by the Operator or OEM of

the device. Certified apps have permissions to most Web APIs. Privileged: Web apps that have been reviewed, approved, and digitally signed by an autho-

rized Marketplace. As already said, Mozilla doesnt claim to be the one and only marketplacefor Firefox OS applications. Privileged apps have access to less APIs than certified apps.

Web: Non-privileged hosted or packaged apps again have less APIs available than privilegedapps. Mainly, all apps of type web are considered as untrusted web content.

As we will see in the next chapter, an app must explicitly require API access via the apps Manifest.If the requested permission is granted by gatekeeper Gecko mainly depends on the apps trust level.An app may become privileged by submitting it for consideration to an authorized Marketplace. In

fact, a hosted app never can become privileged or certified. So if one needs access to certain APIs,packaging the app might be required at some point.

On runtime, each app is fully separated from other apps that may run at the same time (sandbox-ing). Technically speaking, each app runs in its own process.


16/44

4 The Manifest file (available)4.1 Meta information about an app

We already learned that Firefox OS apps basically are regular web apps with an additional JSONmanifest file and access to certain device and platform features. The manifest file is namedmanifest.webappand is stored in the root folder of an app. A valid manifest file may look likethis:

1 {

2 "version": "0.1",

3 "name": "Twitter Demo Client",

4 "description": "Twitter Demo Client from Firefox OS book",

5 "launch_path": "/index.html",

6 "icons": {

7 "64": "/img/icons/twitter-64.png"

8 },

9 "developer": {



12 },13 "installs_allowed_from": ["*"]

14 }

Mozilla offers an online manifest schema validator which is very helpful. Also the Firefox OSSimulator for the Firefox Browser does validate the manifest and points the developer to issues.

When serving the manifest.webappfile from a webserver one needs to make sure that the file isserved with a Content-Type header ofapplication/x-web-app-manifest+json, e.g. by adding thefollowing to the Apache web server configuration:

1 AddType application/x-web-app-manifest+json .webapp

However, this is important only for hosted apps, but not for packaged apps.

https://marketplace.firefox.com/developers/validator
https://marketplace.firefox.com/developers/validatorhttps://marketplace.firefox.com/developers/validator


17/44

The Manifest file (available) 12

4.2 App settings

In fact, the manifest can be very slim. There are basically only two self-explanatory required fields-

thenameand descriptionof the app.The launch_pathis also required for packaged apps and can be used to specify the entry point ofthe web app. If given, the path needs to be an absolute URL.

The value forversioncan mainly be whatever one likes, but to support the update process its helpfulto apply an incremental numbering scheme.

An app can have multiple icons, mainly in different sizes. For Windows 7 and Android, the followingicon sizes are supported:

16 x 16

32 x 32 48 x 48

64 x 64

128 x 128

256 x 256

For Firefox OS icons should be provided without a drop shadow in the following sizes:

30 x 30

60 x 60

A 128 x 128 icon is required when submitting to Firefox Marketplace.

By using type the developer may specify the app type. The value defaults to web, other possiblevalues areprivilegedand certified.

Viaorientationone can lock the orientation, even if the device orientation changes. That might behelpful in cases where an app is made for either working in portrait or landscape orientation. Usingthe values portrait-primary, landscape-primary, portrait-secondaryor landscape-secondaryprovide even more fine-grained settings.

One can set fullscreento trueor falseto indicate whether the runtime should launch the app in

full-screen mode. It defaults to false. When set to true, the status bar is made invisible as well.

With the help oflocalesone may override values from the manifest with localized values:


18/44


1 "locales": {

2 "es": {

3 "description": "Accin abierta emocionante del desarrollo del Web!",

4 "developer": {

5 "url": "http://es.mozillalabs.com/"

6 }

7 },

8 "it": {

9 "description": "Azione aperta emozionante di sviluppo di fotoricettore!",

10 "developer": {

11 "url": "http://it.mozillalabs.com/"

12 }

13 }

14 }

One may override any values from the manifest except default_locale, localesand installs_-allowed_from. The idea behind overrides is to provide localized manifest content (e.g. description,icons, etc.) to international users. There is no direct relation between locales given in the manifestand localizations of the app itself. However, its good practice to only include locales in the manifestfor which also localizations of the app itself exist. Iflocalesis present,default_localeneeds to bepresent as well indicating the locale which serves as the default.

The directiveappcache_pathmay point to the app cache manifest that supports offline operation:

1 "appcache_path": "/cache.manifest"

A later chapter in this book is dedicated to apps working offline.

With the directiveactivities one may specify the Web Activities that the app supports and providesto other apps:

1 "activities": {

2 "share": {

3 "filters": {

4 "type": [ "image/png", "image/gif" ]

5 },

6 "href": "foo.html",

7 "disposition": "window",

8 "returnValue": true

9 }

10 }


19/44


In the snippet above,shareis the activities identifier. There are certaindefault identifiers defined byGaia. In addition, a web app can define its very own activities by simply using a custom identifier.

Thehrefis opened if the app is chosen to perform an activity. The key dispositionis optional and

can take the valueswindow

andinline

. Whilewindow

opens the app in a new window,inline

usesa layer over the calling app to display the supporting app. The key returnValueshows if the activitywill return a value or not. Viafiltersthe apps are determined that are suitable for handling a givenactivity. Like the activity identifiers, the keys are free-form text and can be named as desired. Allfilters must be satisfied by an application to qualify as being able to handle the activity requested.We will take a closer look at the exact mechanics of Web Activities later in the book.

4.3 Developer settings

The developersection allows to state information about the developer-its nameand a url for more

information on the web. Both is required only when submitting to Firefox Marketplace.

4.4 Permission settings

It the app wants to access certain WebAPIs, this needs to be declared in the manifest file. For mostof the apps the user has to give permissions to the app on first launch. For each API, one needs tostate the intented operation as well: read, readwrite, readcreate or createonly.

1 "permissions": {

2 "contacts": {3 "description": "Required for autocompletion in the share screen",

4 "access": "readcreate"

5 }

}

In this example, the Contacts API is used to read data from the devices contact list as well as forcreating new records. A description that reflects the intent is required for each permission inthe list. However, there are WebAPIs that are available by default. In this case, one can omit thepermissions request.

With the installs_allowed_from directive a developer can limit the app installations to certainorigins. If one wants to distribute only via Firefox Marketplace the following statement will work(no trailing slash at the end of the URL!):

https://developer.mozilla.org/en-US/docs/WebAPI/Web_Activities#Firefox_OS_activities
https://developer.mozilla.org/en-US/docs/WebAPI/Web_Activities#Firefox_OS_activitieshttps://developer.mozilla.org/en-US/docs/WebAPI/Web_Activities#Firefox_OS_activitieshttps://developer.mozilla.org/en-US/docs/WebAPI/Web_Activities#Firefox_OS_activities


20/44


1 "installs_allowed_from":["https://marketplace.firefox.com"]

The wildcard (star-symbol) means any origin is fine, will no content in the brackets means no originwill work.

With thecspdirective, one can specify a Content Security Policy for the app that can be understoodas a specialization of theSame Origin Policythat is used by default.

// todo

https://developer.mozilla.org/en-US/docs/Web/JavaScript/Same_origin_policy_for_JavaScript
https://developer.mozilla.org/en-US/docs/Web/JavaScript/Same_origin_policy_for_JavaScripthttps://developer.mozilla.org/en-US/docs/Web/JavaScript/Same_origin_policy_for_JavaScript


21/44

5 WebAPIs by example (partlyavailable)

We already learned that a web app may access device features by utilizing WebAPIs. Some of theWebAPIs provided are part of the HTML5 standard, others are new APIs added by Mozilla. Mozillaoften submits these APIs to the W3C to make official standards out of them at someday. For manyAPIs, the W3CsSystem Applications Working Groupworks on theses standards with an ultimategoal:

[] to define a runtime environment, security model, and associated APIs for buildingWeb applications with comparable capabilities to native applications.

Lets take a closer look at the APIs available today by going through example use cases.

5.1 The Grumpy Phone app (using Vibration API &

Proximity API)

Code download

The code of this demo application is available for download at GitHub.

Today, our Firefox OS device has a bad day. It dislikes to be touched by a human. If no human isclose, it shines in a pretty blue color:

http://www.w3.org/2012/sysapps/https://github.com/michael-romer/firefox-os-book-the-grumpy-phone
https://github.com/michael-romer/firefox-os-book-the-grumpy-phonehttp://www.w3.org/2012/sysapps/https://github.com/michael-romer/firefox-os-book-the-grumpy-phonehttp://www.w3.org/2012/sysapps/


22/44

WebAPIs by example (partly available) 17

Grumpy Phone start page

But if one comes too close, it turns to orange and starts vibrating!


23/44


Angry Grumpy Phone

In hardware devices, the proximity sensor usually is located above the screen. If one takes his hand

and slowly moves from far to close to the sensor, the display turns to orange and the phone vibrates.Move back again and vibration stops, the screen turns back to blue again. All that is needed to buildthis magic is some lines of straight forward JavaScript code and HTML markup:

1

2

3

4

5

6 The Grumpy Phone

7

9

10 html {

11 height: 100%;

12 background-image: -moz-linear-gradient(top,#43BFC7,#008080

13 background-repeat: repeat-x;

14 }


24/44


15

16

17

18

19 window.ondeviceproximity = function (event) {

20 if (event.value < 5) {

21 vibrating = navigator.vibrate(2000);

22 $('html').css('background-image', '-moz-linear-grad

23 ');

24 } else {

25 vibrating = navigator.vibrate(0);

26 $('html').css('background-image', '-moz-linear-grad

27 ');

28 }

29 }

30

31

32

The manifest file as well is as simple as it can be:

1 {

2 "version": "1.0",

3 "name": "The Grumpy Phone",

4 "description": "The Grumpy Phone - A demo app taken from https://leanpub.com/fir\

5 efox-os",

6 "launch_path": "/index.html",

7 "icons": {

8 "64": "/img/icons/grumpy-64.png"

9 },

10 "developer": {



13 },

14 "installs_allowed_from": ["*"]

15 }

As the proximity feature is not available on the Firefox OS Simulator, the app is only really fun ona hardware device. How to use the Vibrate API and the Proximity API is nearly self-explanatory:We register a callback function forondeviceproximitywhich is constantly called automatically. Via

event.valuewe retrieve the distance in centimeter and vibrate for two seconds as well as paint thescreen orange if it is below five centimeters. Thats it!


25/44


5.2 More Web APIs (TODO)

5.2.1 Screen Orientation API

Description: Get notification when screen orientation changes as well as control which screenorientation a page/app wants.

Security Level:

W3C Standard:

5.2.2 Geolocation API

Description: Known as part of the HTML5 standard family, this API gives access to the endusers location.

Security Level: W3C Standard:

5.2.3 Open WebApps API

Description:

Security Level:

W3C Standard:

5.2.4 Battery Status API Description: Information about battery charge level and if device is plugged in.

Security Level:

W3C Standard:

5.2.5 Alarm API

Description: Allows to schedule a notification.

Security Level:

W3C Standard:

5.2.6 Time/Clock API

Description: Setting the current time.

Security Level:

W3C Standard:


26/44


5.2.7 WebFM API

Description: Accessing the FM radio feature.

Security Level:

W3C Standard:

5.2.8 IndexedDB API

Description: With the help of IndexedDB one can easily store structured-data on the clientdevice. IndexedDB also allows searching.

Security Level:

W3C Standard:

5.2.9 Ambient Light Sensor API Description: Access to the ambient light sensor of the device.

Security Level:

W3C Standard:

5.2.10 Proximity Sensor API

Description: Access to the proximity sensor of the device.

Security Level:

W3C Standard:

5.2.11 Web Activities

Description: With the help of Web Activities one app can delegate an activity to another appwhich declared to be able to handle a specific activity. As this API is a key concept to theFirefox OS platform, I dedicated a later chapter to this topic.

Security Level:

W3C Standard:

5.2.12 WebPayment API

Description: Another key API is the WebPayment API which allows web apps to initiatepayments and refunds for digital products. A later chapter is dedicated to this topic.

Security Level:

W3C Standard:


27/44


5.2.13 TCP Socket API

Description: Low-level networking API with SSL support.

Security Level:

W3C Standard:

5.2.14 Device Storage API

Description: Read/write access to specific locally stored files and folders.

Security Level:

W3C Standard:

5.2.15 Contacts API

Description: Accessing contact data available on the device in a read/write manner. Security Level:

W3C Standard:

5.2.16 Browser API

Description: Enables implementing a browser completely in web technologies.

Security Level:

W3C Standard:

5.2.17 WebTelephony API

Description: Allows accessing the telephony capabilities of the device.

Security Level:

W3C Standard:

5.2.18 WebSMS API

Description: Send, receive and manage short messages stored on the device.

Security Level:

W3C Standard:

5.2.19 Idle API

Description: Sends a notification when the user is idle.

Security Level:

W3C Standard:


28/44


5.2.20 Settings API

Description: Accesses the system-wide device settings.

Security Level:

W3C Standard:

5.2.21 Power Management API

Description: Allows actions like turning of the screen or cpu.

Security Level:

W3C Standard:

5.2.22 Mobile Connection API

Description: Exposes information about signal strength, operator, etc. This API only worksfor a mobile connection and does not take WiFi into consideration-a dedicated API exists forWiFi related information.

Security Level:

W3C Standard:

5.2.23 WiFi Information API

Description: Comparable to the Mobile Connection API, the WiFi Information API returns

WiFi related data such as the the list of available WiFi networks, signal strength and name ofcurrently connected network.

Security Level:

W3C Standard:

5.2.24 WebBluetooth API

Description: Low-level API to deal with bluetooth on a device.

Security Level:

W3C Standard:

5.2.25 Permissions API

Description: Allow Settings app to manage all app permissions in a centralized location.

Security Level:

W3C Standard:


29/44


5.2.26 Network Stats API

Description: Retrieve information about data usage.

Security Level:

W3C Standard:


30/44

6 Web Activities by example (partlyavailable)

6.1 Introduction

The core idea behind Web Activities is that web apps should be able to work together. While oneweb app may state a user intent using an API, other apps may declare to be able to handle actionsrequested from other apps. One supports the other. If more than one web app declares to handlecertain actions, the user is prompted to choose the app he wants. Heres an example: An app wants

to retrieve a picture, either from the phones camera or gallery. The user is prompted and decideswhich way to go. Once the picture is taken, the calling app retrieves it (as a binary large objects, aso-called BLOB, in this case).

One may have heard aboutWeb Intentsbefore, an initiative mainly driven by Google. The ideaof Web Intents is very similar to Mozillas Web Activities and in fact Web Activities is a counter-proposal to Web Intents. Currently, Web Intents has been put on hold after Google faced some issuesenabling it in Google Chrome for a while.

6.2 The Funny Faces app (Pick Activity)

Code download

The code of this demo application is available for download at GitHub.

Now its time to put a red nose on! The Funny Faces app works like this: First, a face close-up photois taken:

http://webintents.org/https://github.com/michael-romer/firefox-os-book-funny-faces
https://github.com/michael-romer/firefox-os-book-funny-faceshttp://webintents.org/https://github.com/michael-romer/firefox-os-book-funny-faceshttp://webintents.org/


31/44

Web Activities by example (partly available) 26

Take a close-up photo

This is done either via the phones built-in camera (doesnt work on the Firefox OS Simulator) ortaken from the phones image gallery:


32/44



The persons nose needs to be right in the middle of the screen:


33/44



Once the picture is taken, a red nose can be put on by hitting the nose!


34/44



Funny, isnt it? ;-)

The apps code is straight forward:

1

2

3

4

5

6 Funny Faces

7 8

9

10

11 #content {

12 margin: 0;

13 padding: 0;


35/44


14 }

15 #myCanvas {

16 margin: 0;

17 padding: 0;

18 }

19

20

21

22

23 Funny Faces

24

25

26

27

28

29 Restart


36/44


56 alert("Image could not be loaded :-(");

57 };

58

59 function handleStart(evt) {

60 evt.preventDefault();

61 var touches = evt.changedTouches;

62 var touch = touches[0];

63 var radius = 70;

64 cx.beginPath();

65 cx.arc(touch.pageX-2, touch.pageY-2, radius, 0, 2 * Math.PI, false)

66 cx.fillStyle = 'red';

67 cx.fill();

68 cx.stroke();

69 }

70

71

72

The main aspects are MozActivityand a HTML5 canvas element. To make our lives easier, we utilizejQuery and jQuery Mobile as well, however, its not really needed and doesnt matter that muchhere. It gets more interesting when MozActivityis created using namepickwhich is a Gaia defaultActivity. Viadata, the file type required is given. ViaMozActivity, the Firefox OS camera or galleryapp is invoked and if all went well pick.onsuccessis invoked. It paints the photo taken onto thecanvas 2D context. The function handleStart has been added as a listener for the touchstart event.It simply adds a filled circle (in red color) on top of the canvas once the screen is tapped. Thats all!

6.3 More Web Activities (TODO)


37/44

7 Programming the Firefox OS WebRuntime (partly available)

7.1 HTML & CSS (TODO)

7.2 JavaScript (partly available)

7.2.1 Introduction

JavaScript (JS), also known as ECMAScript, is the lingua franca of the web, a loosely-typed, case-sensitive, object-oriented language. But when we talk about JavaScript, we talk about more thanjust a programming language. There is also the DOM, the Document Object Model, an APIfor working with documents, that are written in an xml-like syntax, such as HTML. The DOMis represented by the documentobject. Everything that starts with documentin JS code deals withthe DOM. However, the DOM actually is nothing special to JS - at least not anymore. Since it hasbeen standardized by the W3C, its a language-independent API standard used in conjunction withseveral programming languages such as PHP.

And the there is the so-called BOM, the Browser Object Model. The BOM is less standardizedcompared to the DOM, however, since HTML5 there is some progress in this direction. While the

DOM mainly allows to interact with a document, the BOM allows to interact with the browser,programatically. Usually, the BOM is represented by the window object, which also serves as theglobal namespace, which is where all things defined go to, which arent encapsulated in anotherobject or a function (which itself is an object, by the way). This has some interesting implications.Calling alert('Message!') to bring up a native browser modal dialog is the same as calling

window.alert('Message!'). The window part is automatically prepended - but it does exist. Thefunctionalerttherefore isnt magically provided by the runtime engine, but simply is a method ofthe windowobject. In fact, therefore even documentsimply is a property of the windowobject anddoesnt sit there independently.

It exists a single windowobject for each tab or special windows in a browser. However, thewindows

object has methods which affect the overall container hosting all of the tabs. Anyway - this is notthat important for us since on Firefox OS devices Open Web Apps dont deal with tabs at all.

7.2.2 Adding JavaScript

Multiple options for adding JavaScript to a Web App exist. If the JavaScript code is embedded in aHTML file, its called inline script:


38/44

Programming the Firefox OS Web Runtime (partly available) 33

External JavaScript files may be embedded like this:

Whatever way of adding JavaScript is used, whenever the browser encounters a script tag, it loadsthe code and interprets it before it resumes processing the HTML. This means that the order of

loading scripts matters-if one script block defines a function another script block depends on, thelatter must come second. And it also means that one will want to include scripts as late in the sourcecode as possible.

7.2.3 Variables

A variable is easily defined:

var a = 1;

Theres no need to state a specific types. Simply put a varin front always (if the var is omitted,which is possible indeed, we create a global variable instead). As long as no value is assigned, the

variable holds the valueundefined. In addition, there are the primitive value types string,boolean(trueand false), number(this includes float and int values!) and nullavailable in JavaScript. Onecan find out a current value type using the type operator:

var text = A text; typeof text; // returns the string (!) string

In terms of variable naming, we cant use a number in the front, but letters, underscore or the dollarsign will work. Numbers work as well, simply not in the front.

Arrays can be defined in two different ways. One may use the more verbose

var arr = array(a, b, c, d);

// todo

7.2.4 Functions

A function declaration in JavaScript is simple:

function myFunction(arg1, arg2, arg3) { return arg1 + arg2 + arg3; }

A function that doesnt return a value always returns undefined. Usually this isnt very much ofinterest, however, e.g. when working on an interactive JS shell such as the one provided by NodeJSor Rhino, the undefinedsometimes is printed:

1 $ console.log("Log me");

2 > Log me

3 > undefined

So one shouldnt get confused here.


39/44


There are some more interesting things about function one should know. For instance, there is thefact that functions are objects (Function) with local variables and methods. A function object e.g.references an array-likeargumentsobject corresponding to the arguments passed to a function.

Then there also is no concept of default values of parameters. If one is experienced with otherprogramming languages such as PHP, this might be surprising. If one wants to default a parametervalue, this needs to be implemented by hand in a functions body. This especially is useful as thereare no required parameters as well. A function can be called with less or more parameters thandesigned. If we define the following function:

1 $ function sum(a, b, c, d) { return a+b+c+d; };

7.2.5 Variable Scope

Closely related to functions in JS is the

7.2.6 Select DOM elements

To select DOM elements for manipulation, different options exist. Historically, functions like

var elem = document.getElementById(id);

were the tool of choice. With the raise of JavaScript libraries such as jQuery, more powerful functionswere offered to the JavaScript developer:

var elem = $(#id);

jQuery allows to provide a css selector like query to its$function (one should not get confused here-the$ simply is a short, but valid JavaScript function provided by jQuery-its not a native JavaScriptfunction).

Since HTML5, another option is available-the selectors API. It allows to query DOM elements in ajQuery-like manner:

var elem = document.querySelector(#id);

7.3 Firefox UI Build Blocks & Transitions (partly

available)Mozilla runs a web portal calledBuilding Firefox OS which mainly serves as a UI componentscatalog. It has its roots in Gaia, the official phone UI. Gaia in fact is a collection of apps sharing acommon look & feel. Its the nature of the web, that websites and apps look different and also FirefoxOS puts no restrictions on the UI of the apps installed. One may come up with a fully custom UI

http://buildingfirefoxos.com/
http://buildingfirefoxos.com/http://buildingfirefoxos.com/


40/44


which has nothing in common with other apps with the Firefox OS look & feel. Thats absolutelyfine and it is not any different e.g. from the iOS platform.

However, if one wants to build a Firefox OS app that seamlessly integrated with the overall look and

feel of Firefox OS, the UI components catalog comes in handy. Not only its a visual guideline, butmuch more re-usable UI code, a UI components code library, if you will.

The best way to get started with the UI library is todownload the codeas a zip file and cherry pick.But on thedownloads pagethere is even more:A photoshop based icon set,design stencil kitaswell thedefault fontused called Feura Sans.

To go native UI-wise is also a matter of the initial situation as well as the purpose of the app. If anexiting mobile website should be made available as an Open Web App to Firefox OS device, simplyadding only the Manifest might be the way to go. In other cases, especially when designing an appfrom scratch, that targets Firefox OS devices, picking up the Building Blocks might be the way to goto speed up development and to build apps that look native.

In addition to UI components, Building Firefox OS also provides support for transitions, UIanimations based on CSS, that are used to open dialogs, in-app navigations and more. They aremainly useful when building so-called Single Page Apps.

7.4 Single Page Apps (partly available)

While you can add several HTML files to your packaged app and link between them like you woulddo with in a typical browser based website. However, on a mobile device and compared to nativeapps, this feels clunky. Often, there will be full white screens between one page and another-there

is no smooth page transition animation displayed.Even one could build a single page app from scratch, due to the complexity given, it is helpful to pickup one of the popular single page app frameworks out there. In this book, we will use AngularJS,which is a very good choice.

https://github.com/buildingfirefoxos/Building-Blocks/archive/gh-pages.ziphttp://buildingfirefoxos.com/downloads/https://mozilla.box.com/s/jp5lrplbuont96ypm27qhttps://mozilla.box.com/s/5ucf52a98q1rd20eu5lmhttps://github.com/mozilla-b2g/moztt/tree/master/FeuraSans-1.0http://angularjs.org/
http://angularjs.org/https://github.com/mozilla-b2g/moztt/tree/master/FeuraSans-1.0https://mozilla.box.com/s/5ucf52a98q1rd20eu5lmhttps://mozilla.box.com/s/jp5lrplbuont96ypm27qhttp://buildingfirefoxos.com/downloads/https://github.com/buildingfirefoxos/Building-Blocks/archive/gh-pages.ziphttp://angularjs.org/https://github.com/mozilla-b2g/moztt/tree/master/FeuraSans-1.0https://mozilla.box.com/s/5ucf52a98q1rd20eu5lmhttps://mozilla.box.com/s/jp5lrplbuont96ypm27qhttp://buildingfirefoxos.com/downloads/https://github.com/buildingfirefoxos/Building-Blocks/archive/gh-pages.zip


41/44


7.5 HTML5 canvas (TODO)

7.6 Working offline (TODO)

7.7 jQuery Mobile UI framework (TODO)

7.8 WebGL (TODO)


42/44

8 Distributing apps (partly available)8.1 Introduction (TODO)

8.2 Distributing via a website (TODO)

8.3 Submitting to a Marketplace (available)

Before an app can be submitted, a developer account needs to be created. The Firefox Marketplace

relies onPersona, Mozillas identity management system. Setting up a persona account can simplybe done by providing a valid email address and a password of choice.

Once the Persona account is confirmed by clicking the link in the email from the Persona system,joining the Firefox OS Marketplace developers programcan be done in just a few steps.

After approving the terms and conditions, one needs to select the apps target devices and operatingsystems. We already learned that Firefox OS can run on Android systems as well, if Firefox forAndroid is installed on the device. We will focus on the Firefox OS devices in the following.

Next, app submission is different for hosted and packaged apps. The Firefox Marketplace does notoffer website hosting, which means that submitting a hosted app requires to provide the apps URL.

On the contrary, when submitting a packaged app, the zipped source codes must be uploaded.Packaged apps are stored and served from the Firefox Marketplace. We will focus on uploadinga packaged app in the following.

When uploading, Firefox Marketplaces automatically does a sanity check on the code provided. Forinstance, when submitting an app, a 128px icon must be included in the packages, otherwise thefollowing error is raised: An icon with a minimum size of 128x128 must be provided by each app..

At this stage, all errors reported must be fixed. Once done, it is time to decide if the app will befree or must be paid. On the next screen Firefox Marketplace prompts for some more applicationdetails. This is the first place, where app marketing takes place. Good screenshots and descriptiondrive sales.

If the app is fee-based, the Firefox Marketplaces prompts for the payment details on the last screen.This is where the app price is defined as well as where the application developers bank account isconfigured for the royalty payments. At this stage it is possible to switch between a free and a paidtier.

https://login.persona.org/https://marketplace.firefox.com/developers/submit/terms
https://marketplace.firefox.com/developers/submit/termshttps://login.persona.org/https://marketplace.firefox.com/developers/submit/termshttps://login.persona.org/


43/44

Distributing apps (partly available) 38

Once all info is given, the app is in review state. On the Marketplaces Developers Hub page forsubmitted apps, one can also find information about the estimated waiting period for the app reviewby Firefox Marketplace. It is even stated how many other apps are on the waiting list. At the time ofwriting, a waiting period of 20 days or is reported. However, often, feedback on an app submission

is sent much more earlier.

One missing piece of the puzzle yet is the so-called Mini Manifest. It is created by the FirefoxMarketplace on app submission automatically. The Mini Manifest of an app is stored on the phonewhen once app is installed. The Mini Manifest is updated regularly automatically, usually once aday. The Mini Manifest contains more meta data on the app, partly taken from the apps Manifest,partly added by the Firefox Marketplace.

8.4 App updates on a Marketplace (available)

Updating a packaged app on a Marketplace mainly means uploading the new version and resub-mitting it. The app needs to pass the review process again then. Once it is approved, an app updateis triggered to the phones. The update mechanics are mainly based on the Mini Manifest of anapp. The Mini Manifest includes the package_path, which points to the zip containing the appscode. Technically, the phone checks the zipsHTTP ETagheader to learn if an updated version isavailable. It is interesting to see, that again simply standard Internet technology is used by FirefoxOS to power things like app distribution.

https://marketplace.firefox.com/developers/submissionshttp://de.wikipedia.org/wiki/HTTP_ETag
http://de.wikipedia.org/wiki/HTTP_ETaghttps://marketplace.firefox.com/developers/submissionshttp://de.wikipedia.org/wiki/HTTP_ETaghttps://marketplace.firefox.com/developers/submissionshttps://marketplace.firefox.com/developers/submissions


44/44

9 Modifying the Firefox OS core UIGaia (TODO)

Developing Apps for Firefox OS

Documents

Transcript of Developing Apps for Firefox OS