Mozilla Hacks

Introducing the Firefox OS Boilerplate App

By Robert Nyman [Editor emeritus]

Posted on January 30, 2013 in Featured Article and Firefox OS

When coming to a new platform or context, it’s always good to get a peek at some code and examples how to make things work. With Firefox OS and app development, it’s just the web with a few additions.

Before here at Mozilla Hacks, we’ve covered a few ways to get started with building apps for Firefox OS:

My experiences

Lately I’ve been fortunate enough to give and take part in a number of workshops around Firefox OS, to see developers trying to build things for it, port their existing web apps and much more.

This has been a fantastic learning lesson for me, and it’s been crucial to see where people might need pointers, help or examples!

The Firefox OS Boilerplate App

This led to me creating the Firefox OS Boilerplate App. As the name implies, it’s there to provide you with the most basic features to get started with building an app from scratch, or tools to port your existing web app.

The idea is also to avoid any dependency on external libraries or resources, but rather be self-contained.

It contains:

  • An install button, offering you to install it as a hosted app
  • Web Activities – lots of examples and use cases
  • WebAPIs in action
  • Offline support (disabled by default)
  • Packaged apps – install your app as a ZIP file

It’s available on GitHub:

How to use it

The easiest way to get started, installing it and testing the various features, is to navigate to the Firefox OS Boilerplate App in the web browser on a Firefox OS device or in the Firefox OS Simulator.

Alternatively, install it in the Firefox OS Simulator Dashboard by providing either of these URLs:

Running it locally

Once you’re ready to get started developing, download the code and run it on a web server, or point out your local version of the Firefox OS Boilerplate App in the Firefox OS Simulator.

Note: make sure that the paths in the manifest file are valid on your localhost – bear in mind that these paths are relative to the root of the web site they are being served at.

Also make sure to configure your server to send the manifest file with the right Content-type: application/x-web-app-manifest+json.

This is, for instance, easy to set up in an .htaccess file in Apache:

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

Offline support

I’ve provided an .appcache file for enabling offline support (it’s disabled by default).

To enable offline capabilities, just add this to the index.html file:

Please make sure to do your homework before enabling offline support, to avoid possible initial issues:

Remember that the .appcache file has to be served as a text/cache-manifest file:

AddType text/cache-manifest .appcache

Packaged apps

When you develop web apps, by default they are being delivered from a server, thus needing online connectivity or offline support to be enabled, to work as expected.

You do have another option, though, which is packaged apps. Basically, what this is, is putting all the files of your app into a ZIP file, making them available directly on the device itself.

Packaged apps can also request an elevated access to certain WebAPIs in Firefox OS that aren’t available to hosted apps (we’ll go more into the differences in a later post here on Mozilla Hacks).

There are a couple of files included in the Firefox Boilerplate OS App to help you get started, if you are interested in this.

To create and install a packaged app, you need to go through a few steps:

  • ZIP all app content (not containing folder), including regular manifest
  • Create a mini manifest (the package.manifest file) and make sure the “package_path” is absolute to where the ZIP is located
  • Developer name and info has to match between mini manifest and the regular one in the ZIP file
  • Have an installPackage call in JavaScript pointing to the mini manifest (instead of the regular install one) – this is shown in comments in the base.js file
  • Turn on Developer Mode in the Firefox OS Simulator (Settings > Device Information > More Information > Developer > Developer mode)
  • Add type property (e.g. "type" : "privileged") in the manifest if you want access to certain APIs

Work in progress

The Firefox OS Boilerplate App is a work in progress, meaning that it’s likely to change over time. I believe, however, that it gives you a good head start and look into what’s possible with web apps in Firefox OS.

Hope you like it, and please let me know what you think!

About Robert Nyman [Editor emeritus]

Technical Evangelist & Editor of Mozilla Hacks. Gives talks & blogs about HTML5, JavaScript & the Open Web. Robert is a strong believer in HTML5 and the Open Web and has been working since 1999 with Front End development for the web - in Sweden and in New York City. He regularly also blogs at http://robertnyman.com and loves to travel and meet people.

More articles by Robert Nyman [Editor emeritus]…

36 comments

  1. Rodolfo De Nadai

    Owww!! That’s great!
    This for sure make the life easiear for developers…

    Great work…!

    January 30th, 2013 at 02:57

    1. Robert Nyman [Editor]

      Thank you, I hope so!

      January 30th, 2013 at 03:02

  2. mpmedia

    please incluse some tests along , so we can learn how to write tests for a firefox os app, and why not including a mocking framework for firefox os api too ?

    January 30th, 2013 at 03:13

    1. Robert Nyman [Editor]

      I believe that’s out of the scope for the Boilerplate. It’s all good things, but then I believe it would grow and become too big, and not being an as easy and bare-bones approach as it is today.
      I believe Mortar would be a better fit for that, and they that these options can complement each other.

      On the topic of tests, best place is probably to look at the tests in Gaia (the UI for Firefox OS).

      January 30th, 2013 at 03:46

  3. zalun

    As for running it locally I found a little python script if someone (like me) is not fancy running apache: https://gist.github.com/4640534 just place in directory of the app and run “python serveapp.py“ it’s gonna be on port 3000

    January 30th, 2013 at 03:24

    1. Robert Nyman [Editor]

      Ah, nice – thanks for the tip!

      January 30th, 2013 at 03:46

  4. rg

    How do you build gaia’s ui block ( http://buildingfirefoxos.com/ ) in this boilerplate ? Is there any stylesheet to import ?

    January 30th, 2013 at 04:01

    1. Robert Nyman [Editor]

      Right now, you need to copy the files and code from those building blocks into your own app to make it work (i.e. your app won’t have access rights to the files in Gaia).

      We will also have a future blog post here on Mozilla Hacks about the Gaia Building Blocks – stay tuned!

      January 30th, 2013 at 04:58

  5. Fernando Briano

    This is great! Just yesterday I ported my first webapp and tested it in the Firefox OS Simulator. I’ll add offline support now that I’ve read about it. It’s a great starting point for new developers, thanks!

    Now if I can just get one of those Peak phones :D

    January 30th, 2013 at 04:39

    1. Robert Nyman [Editor]

      Thank you, glad you like it!
      And yes, I’d like one of those too. :-)

      January 30th, 2013 at 04:41

  6. Jaydson Gomes

    Oh, nice!
    This boilerplate is exactly i was looking for :)
    BTW, FirefoxOS is the most exciting technology of all time.

    January 30th, 2013 at 06:10

    1. Robert Nyman [Editor]

      Thanks, that’s makes me very happy to hear! :-)

      January 30th, 2013 at 07:34

  7. Joshua Ols

    Very handy, that’s for sure. Now I’m going to have some fun refactoring this to use jQuery and Backbone. :p

    PS.
    Will you guys support custom launchers for the homescreen?

    I ask because personally I’m not fond of the iOS-style metaphor of the homescreen as the app manager. If possible, I’d like to write something more akin to the custom Android launcher “Action Launcher” where I could just put quick access app links on the homescreen, and have a slideout alphabetical list of all apps for those I use less frequently.

    Any thoughts?

    January 30th, 2013 at 06:18

    1. Robert Nyman [Editor]

      Sounds good!

      When it comes to launchers, I don’t really know at this time. I definitely agree with you and think it would be a great alternative. Right now you can hack Gaia (the Firefox OS UI) yourself and push updates to the phone, but I don’t believe you would have access enough as an app, through APIs and more, to change the actual home screen.

      January 30th, 2013 at 07:38

  8. Peter Bengtsson

    Is there a website for automatically creating the icons? For example, if I have a 199×199 jpg, can it spit out a rounded pngs at 60×60.

    January 30th, 2013 at 09:54

    1. Robert Nyman [Editor]

      Happy you asked! I mentioned it in the README for the GitHub repository:
      There’s a great resource with instructions, downloadable examples etc in the Firefox OS app icons style guide.

      January 30th, 2013 at 10:48

      1. Peter Bengtsson

        What I meant was a web service that can help un-photoshop people like me to generate the right sized icons from any image.

        If there isn’t such a web service; I’d happily write one.

        January 30th, 2013 at 17:31

        1. Robert Nyman [Editor]

          Ah, I see. Well, if it’s only resizing existing images, I’m sure there are options out there. Personally, though, I think that would probably lead to non-optimal icon design (since it’s not just about size).

          I’d rather recommend taking any of the templates from the icon style guide and use online editing services like Pixlr or online Photoshop and then adapt them to what you want it to look like.

          January 31st, 2013 at 02:27

  9. Rob Hudson

    Similar to what zalun commented above for hosted apps, I wrote a script to serve packaged apps locally. It does on the fly zipping of the contents and also handles the mini-manifest. If you’re developing packaged apps and have a device to test with it can help. Would love feedback and bug reports:
    https://github.com/robhudson/packaged-app-server

    January 30th, 2013 at 21:20

    1. Robert Nyman [Editor]

      Thanks Rob, that’s great!

      January 31st, 2013 at 02:27

  10. Tin Aung Linn

    This is really help me to get understand the workflows.

    Thanks you guys.

    February 1st, 2013 at 03:10

    1. Robert Nyman [Editor]

      Great to hear!

      February 1st, 2013 at 04:17

  11. zalun

    Can’t find “Developer mode” in “Settings > Device Information > More Information > Developer” on Simulator, desktop B2G or Unagi phone.

    Is there any other step which enables that setting?

    As soon as “type”: “privileged”, appears in manifest, application fails to install :(

    February 4th, 2013 at 04:46

    1. Rob Hudson

      zalun — I believe this is now called “Remote Debugging”? That’s how I was able to get packaged app installs working.

      If your packaged app is of type “privileged” there currently isn’t a way to install this on an actual device, as far as I know. If you run `adb logcat` you’ll see a hint at the error, and it’ll likely be something like invalid package, which means the signing is invalid (b/c it’s not signed).

      February 4th, 2013 at 10:51

      1. Robert Nyman [Editor]

        I know that I’ve tested the Boilerplate with installPackage and installing the ZIP file, but I need to look more into the actual functionality of it.

        February 4th, 2013 at 13:18

      2. Maël Lavault

        sure there is one way. Check the b2g remote
        ff addon on github. I use it all the time to test my privileged packaged app on unagi !

        February 5th, 2013 at 05:46

        1. Robert Nyman [Editor]

          Yes, that works for pushing apps to the device, but it doesn’t enable installPackage from within a web page in the web browser.

          February 5th, 2013 at 07:23

    2. Robert Nyman [Editor]

      I just checked in the Simulator I have, version 1.1pre3, and it’s in there.
      You have all versions available through FTP – best of luck! :-)

      February 4th, 2013 at 13:16

  12. JulienW

    Hey, thanks for this blog post :)

    One correction: the mini manifest for packaged app should be served the same as a webapp manifest, not a cache manifest. Most notably, its mime type is application/x-web-app-manifest+json. So it’s sufficient to name it with a .webapp extension, as you added the Apache configuration already.

    As a rule of thumb, never name a file with a .manifest extension, this is so much overloaded.

    February 4th, 2013 at 06:29

    1. Robert Nyman [Editor]

      Thanks, glad you liked it!

      That’s very interesting on the mini manifest! The documentation on Packaged apps says it should be named package.manifest (and as such, I’d like to serve it with the Content-type that goes with that, to not override other manifest files etc).

      I agree on overusage of .manifest files, but went by the docs (and it worked :-)). I’d be happy to swap it out for package.webapp.

      Can you spread some more light on this?

      February 4th, 2013 at 13:24

      1. Julien Wajsberg

        MDN is not wrong per se but I believe it is misleading:

        – the name of the file has no importance. However, we use to call it update.webapp (because we call it “update manifest” also, as it is used to install and update packaged apps).
        – the Content-Type is clearly application/x-web-app-manifest+json :) However we don’t check this if the origin of the installation website is the same than the origin of the application, and this happens most of the time. Maybe that’s the explanation of why that worked.

        I’ll modify the MDN on this when I have the chance, thanks for pointing it !

        February 5th, 2013 at 00:12

        1. Julien Wajsberg

          BTW, I made https://github.com/julienw/self-updating-packaged-app which can be used to show how a packaged app can update itself too (that works for hosted+appcache app too).

          February 5th, 2013 at 00:14

          1. Robert Nyman [Editor]

            Nice, thanks for sharing!

            February 5th, 2013 at 02:00

        2. Robert Nyman [Editor]

          Thanks, much clearer! I’ve also updated the Boilerplate repository and the blog post.

          February 5th, 2013 at 02:00

  13. Fernando Jiménez

    Hi Robert,

    if I am not wrong, there is no need to name the mini-manifest with an specific name. It just need to be served with the correct Content-type, which, as Julien already mentioned, is “application/x-web-app-manifest+json”.

    You can take a look at the source where we check the Content-type for packaged app installation:
    1. https://mxr.mozilla.org/mozilla-central/source/dom/apps/src/Webapps.jsm#1675
    2. https://mxr.mozilla.org/mozilla-central/source/dom/apps/src/AppsUtils.jsm#237

    The manifest that needs an specific name (“manifest.webapp”) is the one within the zip file (https://mxr.mozilla.org/mozilla-central/source/dom/apps/src/Webapps.jsm#2217)

    Cheers!

    February 4th, 2013 at 14:51

    1. Robert Nyman [Editor]

      Yep, I was totally clear on the one in the ZIP file. But not the mini manifest.
      Thanks for clarifying, that means we can use the .webapp extension for the mini manifest – great news!

      I’ll update the Boilerplate App and post accordingly.

      February 4th, 2013 at 14:54

Comments are closed for this article.