SummerOfCode/2013/FirefoxOSSampleApps

From MozillaWiki
Jump to: navigation, search

Introduction

This page details the deliverables that I produced during Google Summer of Code 2013 for Mozilla. My original proposal is down below and here on top I will details what went right and what went wrong.

The original objective

My original plan was to build one sample app for each API in the WebAPI collection for the 1.0 release of Firefox OS. After talking to my mentor, we agreed that one sample app per API was not a good option due to the schedule and that we should focus on have a small number of real apps.

With that in mind I went on to check what were the most common APIs that the developers were trying to use but were facing difficulties. I do lots of Firefox OS related events in Brazil, on average I am doing two or three events each month. All those events are developer oriented and I talk a lot to people. After many events and workshops I came to the conclusion that the main issue that new developers were facing was not related to the new WebAPI but to the scattered nature of Mozilla documentation. Firefox OS docs are spread over the Mozilla Wiki, Mozilla Developer Network and the Developer Hub of the Firefox Marketplace. New developers were having trouble getting started because they could not understand what they needed.

Thinking about that, I decided to write a quick guide to get new developers up and running. My objective was to have this book ready for the Firefox OS Workshop held on Porto Alegre. I wrote the book in Portuguese and it was very well received by the developers. I've shown the book to my mentor and he allowed me to add this book to the GSoC project. Next I worked on a translation of the book into English and its first version is done.

Besides working on the book, I made five new sample applications that should appear soon in one of the places where we're documenting Firefox OS.

What went right

  • My mentor Marcos Caceres from Mozilla WebAPI team helped me a lot and improved my work by a large margin!
  • The book definitely went right.
  • The sample apps using IndexedDB are a success.
  • The WebActivity sample helped a lot of people.

What went wrong

  • The Gaia Building Blocks could be easier to use.
  • Some APIs are not working as expected.
  • Doing two or three events a month take a lot of time out of the GSoC.

The Future

One of the main objectives of the program is to get new developers engaged with open source initiatives. I think this is a huge success with me since I am now a Mozilla Rep and deeply engaged with Firefox OS. I plan to work even more sample apps and to expand the book after the GSoC is done. I already have some fixes for the apps but due to "pencil down" period I am not allowed to work on them right now.

Below I explain each of the deliverables.

Book

quickguidefirefoxosdevelopment-preview.pdf%20(page%201%20of%2071).png

During my talks and workshop on the many conferences I've been since the GSoC started I've noticed that most users were not having trouble with the WebAPI but we're facing difficulties because the Firefox OS Development documentation is spread over many place such as MDN, Mozilla Wiki, Developer Hub and so on. As an experiment before the Firefox OS Workshop in Porto Alegre, I decided to write a quick guide about Firefox OS development explaining the workflow.

The result was a 70+ pages book in Portuguese that walked the user thru the whole process of installing Firefox Browser and Simulator up to shipping an app to the Firefox Marketplace. I've shown this book to my mentor and we decided to add it to the GSoC project.

I've translated it to English and volunteers will help translating it to other languages. The book is released with a Creative Commons License and Free. I am just waiting my mentor feedback before linking the English version here.

Portuguese Version: http://leanpub.com/guiarapidofirefoxos

English Version: https://leanpub.com/quickguidefirefoxosdevelopment

The book is open source and free, all the Markdown source files for the content are available on GitHub:

English Version Source and Portuguese Version Source

Reception

The Portuguese version has been very well received and has 1000+ readers already. It has proven to be a very good resource and brought new developers to our platform. Its a very good tool to distribute on workshops and forums. The English version received praises from public, volunteers and Mozilla staff. Its about to reach a 1000 readers in the next few days.

Further Work

Volunteers already offered help to translate the book into even more languages and my work after the GSoC is over will concentrate on coordinate this translations efforts and expand the book content to include more sample apps and API documentation. I see this book as a very important resource for acquiring new developers for the platform.

Sample Apps

Besides the book my work included building sample apps to be used for developers to learn more about the WebAPI. I focused on building apps using the most common APIs that are available for plain and privileged apps. I haven't built apps that used APIs that required certified app access because this security level is only available for Mozilla so made no sense.

To present a mix of apps, I've used the Gaia Building Blocks in some apps and jQuery Mobile in others so that the developer is able to check out two different ways of building applications.

Memos

Firefox%20OS%20Simulator.png

Memos is a sample note taking application that uses IndexedDB to store notes.

GitHub Repository: https://github.com/soapdog/memos-for-firefoxos

Implementation

This application uses the Gaia Building Blocks for its UI.

model.js and app.js

All app logic is defined in those two files. Model.js contains the note manipulation routines and app.js contains the application logic.

Usage of WebAPI

Memos uses IndexedDB to store its notes.

Imgur Image Uploader

A sample app for Firefox OS for uploading images to imgur.

It can be used as a standalone app to post pictures to imgur.com as seen in:

uploader1.gif

Or as an activity handler for the share image activity as seen in:

uploader2.gif

Implementation

index.html, share.html and app.js

Those files have the application that the user can launch and use the **Pick Image and Upload** button to select an image from some source and upload it to imgur.com. The share.html file is a copy of index.html that is loaded when the user uses the share activity to send an image from some app to the uploader app. We use this second file because if we use index.html as our activity handler page and the app is already open, it will simply switch to the app without loading the stuff.


imgur.js

This is a minimal imgur.com anonymous upload wrapper. The Imgur API is free to use for non-commercial low volume apps such as this one.


Usage of Web APIs

This application was made to demonstrate the usage of Web Activities. It can act as an activity handler for the *share* activity and it uses the *pick* activity to select images to be uploaded when launched as an app instead of being selected as an activity from the share menu.

You can learn more about Web Activities.

Before trying to upload the image to imgur.com we check if the user is connected using the Connection API.

Upon successfully uploading an image to imgur.com, we display a notification using the Notification API.

GitHub Repository: https://github.com/soapdog/firefoxos-sample-app-image-uploader

ToDos app

A sample app for Firefox OS managing to do lists.

todoapp.gif

Implementation

index.html, app.js and model.js

This app is built similarly to the Memos app. It uses a model.js file to hold the functions responsible for manipulating todo lists and an app.js file that holds the application logic. There are two other files, status.js and util.js that hold auxiliary code.

All the UI is built with the Gaia Building Blocks and index.html holds all the screens.

Usage of Web APIs

This applications uses IndexedDB to store the data and uses the Alarm API to schedule todo item alarms.

Telnet Client

Firefox%20OS%20Simulator.png

A sample app for Firefox OS that is a tiny telnet client. It does not supports ANSI or other control characters. Its only a way to demonstrate the TCP Sockets API

Implementation

This application uses jQuery Mobile to build its UI.

Usage of WebAPI

The TCP Sockets API is used to communicate with the remote server using raw sockets.

Contact Exporter

Firefox%20OS%20Simulator.png

This application exports the device address book to a vCard file on the SD Card.

Implementation

This app uses jQuery Mobile to build its UI. It has a **vcard.js** library that can convert from mozContact to vCard string and an **app.js** file that has the application logic.

Usage of WebAPI

This applications uses the Contacts API to fetch all entries from the address book and uses the Device Storage API to write the vCard file to the SD Card.

Contacts

Proposal

This project is called “Firefox OS Samples” and the objective is to create complete examples for Firefox OS to be placed on the Developer Hub on the Firefox Marketplace. Each sample app should cover one or more APIs from the implemented Web APIs and be fully documented and annotated. Upon reading the annotated source code, running the app and checking the documentation, the developer should have a firm understanding about how to use the given APIs.

Other mobile platforms such as iOS and Android have tons of source code available for developers to look at. Right now we have the source for few apps and the full Firefox OS source but the apps on the Gaia repository are far from simple apps designed for teaching. They are too complex. We need sample code that teaches how to use the WebAPI in an easy way.

There are 33 APIs exposed for the initial release of B2G but some of these APIs are for certified use only. If we keep our samples to the APIs available to hosted and packaged apps, this number falls down to a manageable level that can be done during the GSoC.

These apps would be built using vanilla JS (aka no frameworks) using the Gaia building blocks. By restricting them to this set of technologies, we guarantee that the developer will have a pleasant learning experience from the sample code and that we’ll not depend on third-party libs.

The idea is not to build toys but small apps with some real features that demo the APIs because an important part of learning how to use the WebAPI is learning how it is implemented in real apps. For example: the sample code for the vibration API could be a game like the genius game from the 80s where you must touch the screen following the timing pattern of a vibration.

MDN is full of sample code but not sample apps. We get all those wonderful excerpts of javascript but to fiddle with them we need to wrap them into apps or fiddle with them in the console. A set of well built sample apps would be a valuable resources now that Firefox OS devices are launching and we’re getting ready to revolutionize the mobile market.

I think I am specially good to handle this project because I am a Mozilla Rep working with Firefox OS awareness and training here in Brazil. I’ve been a speaker in many conferences about developing for Firefox OS and I’ve mentored developers during hackathons. I’ve won first and third places in two hackathons here building Firefox OS apps.

As a speaker about Firefox OS development, I often make technical sessions and develop my own sample code to distribute to the users or to show them during the event. I am the team lead for the Brazilian Firefox OS Launch Team and am living and breathing HTML5 apps every day.

Schedule of Deliverables

I am an undergrad student of “Information Systems” at my university. The classes take some hours of my day almost every day. Besides that I have the occasional freelance work but if I am approved as a student for the GSoC, I would not require this freelance work. My only commitments are to my university and to the Firefox OS Launch Team here in Brazil but these tools align well with my Mozilla Community work.

First week of work – ground work

Laying our a boilerplate and deciding on documentation/annotation tool to use for the sample apps. With the little boilerplate done and the documentation tool setup, I am ready to start building sample code for each API.

Two sample apps each week after the first

After the first week, I plan to release two sample code apps per week. Each app should touch one or maybe two related APIs and be fully documented and ready to place somewhere on MDN or the Developer Hub. With seven weeks to use, this gives us a potential of 25 sample apps (25 is a good number, 28 would be a maximum).

Open Source Development Experience

I am a Mozilla Rep and work on Firefox OS awareness. I am yet to submit any pull request to the Gaia repo but I am developing commercial and example apps for Firefox OS here in Brazil. I am the team lead for the Firefox OS Community Launch Team in Brazil.

I’ve been to conferences and hackathons helping lots of developers with code and made many libraries under commercial contracts (closed source unfortunately).

These days I am mostly working with NodeJS, EnyoJS and Javascript and am in the process of releasing my own libraries, I just need to write better docs and tests for them.

Before being involved with the Mozilla Community, I was/am a veteran LiveCode developer. LiveCode is a HyperCard cross-platform clone. I’ve been a speaker on their world wide conferences and am authoring a book (at my own pace) about it. LiveCode is now an FOSS project thanks to the community and the Runtime Revolution company working together to pull the largest UK kickstarter so far. I’ve built many open source libraries for this programming language.

Work/Internship Experience

I have my own company called Amora Labs. I’ve incorporated this year and my company is just me. My idea is to use this company to ship apps and games to mobile platforms.

From 2005 to up until this year, I’ve worked as a contractor for Himalayan Academy Publications building their web backend. I’ve built ecommerce systems, search engines and CMS for them. I’ve been pushing them towards HTML5 based apps but since it’s a Hindu Monastery in Hawaii, they take their time before deciding whats the best course for them. Our work can be seen in their many sites such as http://www.himalayanacademy.com

Academic Experience

I am an undergrad student in the “Information Systems” course at “Unilasalle-RJ” here in my city. Its my first year in this new university since I transferred myself from another institution. So far I am doing great. My headmaster and teachers like me and so do my classmates. I am doing well on my exams and we’re organizing a Firefox OS App Day there.

I have a bachelor degree on social communications and film making from the best film school in the country. I think it is what you call a B.A. in the U.S. I had a great time studying film making and doing my scripts but programming was always in my heart.

Why Me

I am a Mozilla Rep in Brazil. I understand and believe in the Mozilla vision and I have the technical knowledge and desire to those sample apps. I have two geeksphone keons here with me and four android devices running Firefox Aurora, so hardware wise I am in a very good position. I already use many hours of my day for Mozilla related work building apps and helping other developers. This opportunity is a great way for me to learn more and improve my own JS/CSS skills and my knowledge of the WebAPI. As team leader in the Brazilian Firefox OS Launch Team, I must know these technologies inside out and this immersion will make me a better coder and a better Mozilla Rep.

My Mozilla Rep profile is at https://reps.mozilla.org/u/andre/ and my Mozillian page is at https://mozillians.org/en-US/u/andregarzia .

Why Mozilla

It may sound repetitive but I am a Mozilla Rep, so how could I ever let pass the chance to work as a GSoC student for Mozilla? This opportunity is a dream come true. Spending hours each day building sample code to be used by new and seasoned developers will make me very proud. Mozilla is our best hope for a free and open web in the future. I believe in this community and what it stands for and I try to do all I can to make it even better.

I think we must do all we can to make Mozilla stronger and better because it’s the only vendor that stands for us out there in the web. I believe in Firefox OS and want to see it succeed. I think that developing for this new system is the most fun thing I’ve done in a long time (tech wise). I’ve developed for iOS and Android and the joy of using an open system with web technologies is just great! I think that Firefox OS is the best hope for an open future for the mobile web and that the web APIs have the potential to unlock a mobile internet experience that rivals the native apps. I want this future to happen and that’s why I want to invest my time and efforts making the Firefox OS developer community better.