Gaia

My first patch for Gaia, the UI in Firefox OS

There are many ways of contributing to the Firefox OS project and most of these ways do not involve writing code. However, if you are a developer, there is nothing as sweet and satisfying as getting your clean patch pulled into the project. With all the excitement and energy around the Firefox OS platform, I decided it was time for me to make the leap and learn how to hack Gaia — the Firefox OS interface.

There already exists an excellent post about hacking Gaia for Firefox OS, and MDN docs for hacking Gaia is the best starting point.

This post takes a slightly different path, and my focus is more on my experience getting started with hacking Gaia and testing my changes using both Firefox browser and the Geeksphone Keon. I cover the process I went through to choose a bug, write a proposed fix, and submit a pull request to Gaia.

Choosing a bug

Firefox OS uses bugzilla to keep track of bugs. I had occasionally used bugzilla before but this was my first time to actually use it to find a bug to work on. I understand that it is very robust, but the UI can be a bit intimidating for newcomers like me. However, once I spent a bit of time with the various search options, I felt pretty comfortable with it. I ended up picking a bug about a UX enhancement in the clock app. I chose this issue in particular because it is relatively simple and low profile. So I could work on it with little pressure. Here is the issue description that was provided in the comments:

The layout of the alarm list needs adjustment so the user can tell there are more alarms than just 4.

Lets take a look at the clock app and add some alarms to understand what the issue is.

There is no way to see if there are more alarms above or below these four

There are more than four alarms in the above screenshot, but there is no way to know that visually, before starting to scroll, and that is the issue. The bug did not provide instruction on how to fix the problem. I bounced a few ideas with another mozillian about how to solve this problem and decided to use gradients on top and bottom edge to indicate presence of more content. I had seen this type of interaction implemented in other apps before, and it works well.

Proposed solution

I say proposed solution, because I don’t know yet if what I am implementing is acceptable and appropriate. However, it is a lot less work to implement a proposed solution and let people try it; than try to track down all the parties involved and convince them that you have a good idea to solve a UX issue. Even if this solution does not get accepted, the PR will (hopefully) promote some discussions about what would work best. Anyhow, to fix this problem I propose adding two visual elements to the top and bottom of the alarm list. We will use those element to give user a visual clue that there is more content in that direction. Next we will open the clock app within Gaia in Firefox browser to inspect it and figure out what it is made of.

Running Gaia in Firefox

Firefox dev tools are getting better by the day (or the night), and I really like some of the new features. I was very happy to learn that I could debug Firefox OS apps in Firefox.

Currently I know of four different ways to run Firefox OS apps:

Each of these ways have their own pros and cons. At the moment, using Firefox browser is the best way for modifying CSS, inspecting elements, and stepping through the javascript code. I know that there is work underway to bring remote debugging to the simulator, which will hopefully become available very soon. Until then, using Firefox to open a Gaia desktop profile, is the next best thing. There are two important disadvantages to using this method. Firstly, we don’t have access to many of the phone APIs such as orientation sensor, or notifications. Secondly, we are using the latest build of Firefox to get the best developer tools, but as a result we will be using a different version of Gecko than is used by Firefox OS which in some cases may be incompatible. That being said, as long as we can write up our patch using dev tools and then test the app on a physical device, we can be pretty sure that the fix is compatible.

Regardless of which method you choose to run Gaia apps, you need to build Gaia and generate a suitable profile. By default, make command generates a profile directory for a physical phone. I wanted to start inspecting the clock app in the browser, so I use the DEBUG=1 option to generate a gaia profile suitable for desktop. By default DEBUG profile will be created in gaia/profile-debug folder. After a few minutes make will finish and the last line in the terminal will read something like:

    Profile Ready: please run [b2g|firefox] -profile /home/user_name/Projects/gaia/profile-debug

On my system Firefox nightly is installed in /usr/bin/firefox-trunk so I will run the following command to get Gaia running in the browser:

/usr/bin/firefox-trunk -profile /home/user_name/Projects/gaia/profile-debug http://clock.gaiamobile.org:8080

The last argument http://clock.gaiamobile.org:8080 is optional and is used to specify the name of the app you want to run. Instead of `clock`, you can specify the name of any of the certified apps included in Gaia, or any other application that you may add to the `apps` folder in Gaia. For more information about how to do this checkout using Gaia in Firefox.

Making my changes

Before getting any further, lets take care of one very important first step — creating and checking out a branch for the fix.

gaia$ git checkout -b bug-873574-alarm-scroll

Now it was time to open the clock app in Firefox nightly. Right away I started to inspect elements in the app and look at their styles. Since I had a rough idea of the kind of visual effect I was looking for, I started playing around with CSS right in the browser. I used two pseudo elements with a gradient background, one for the top of alarm list and another for the bottom. Here is an snapshot while I was trying to position the pseudo elements properly.

Here is the CSS I ended up with for creating the gradient on top of the alarm list. The code for the bottom gradient is almost the same, except it uses the after psudo element and slightly different margins.

#alarms:before {
  content: '';
  pointer-events: none;
  background: none;
  position: fixed;
  width: 100%;
  margin-left: -1.5em;
  z-index: 10;
  height: 6em;
  margin-left: -1.5em;
}
 
#alarms.scroll-up:before {
  background: -moz-linear-gradient(bottom, rgba(16, 17, 17, 0) 0%, rgba(16, 17, 17, 1) 100%);
  background: linear-gradient(to top, rgba(16, 17, 17, 0) 0%, rgba(16, 17, 17, 1) 100%);
}

Next, I started looking into the Javascript code behind the clock app. Gaia apps are currently written using a bare metal approach, without use of any large libraries or frameworks. That is an interesting topic of discussion, and I would love to see a post looking at pros and cons of this approach. As a frontend developer it does not worry me too much yet. It is too soon to say anything, I have to keep looking at the code and hope that I will identify some common patterns of programming, and figure out how abstraction is achieved.

Now that the visual elements are created, I just need to add a function to toggle the CSS classes on the alarm list element as appropriate. I hook this function up to the scroll event, so every time the user scrolls, it will re-evaluate the need for indicators. It will also need to run whenever an alarm is added or removed to the list. You can how the function is hooked in the PR commit.

showHideScrollIndicators: function al_showHideScrollIndicators() {
    var threshold = 10; // hide indicators when scroll is close enough to an end
    var element = this.alarms;
 
    if (element.scrollTop < threshold) {
      element.classList.remove('scroll-up');
    } else {
      element.classList.add('scroll-up');
    }
 
    if (element.scrollTop > element.scrollTopMax - threshold) {
      element.classList.remove('scroll-down');
    } else {
      element.classList.add('scroll-down');
    }
  },

Here is an example screenshot showing the subtle gradient at the bottom of the list.

alarm_list_indicator_example

Validating Javascript

Since I made some Javascript change, I wanted to validate it with lint. The lint script in Gaia currently relies on google closure lint implementation. In order to install that on debian based systems we need easy install which is bundled inside python setup tools. After that we can install gjslint following these instructions.

$ sudo apt-get install python-setuptools
$ cd /tmp
/tmp$ sudo easy_install http://closure-linter.googlecode.com/files/closure_linter-latest.tar.gz

Once you have gjslint installed, you are good to go. Just very recently a pre commit hook has been added to the project, so that before each commit it will check the files that you have changed against gjslint. If there are any errors, it will point them out to you and stop the commit.

Previewing the changes

You can preview your changes before committing, as well as before submitting your patch to make sure you are not submitting any unintended changes. I like to use a little gtk based app called gitg to preview my changes quickly in a nice interactive GUI. Just type gitg in the command line from the gaia root directory. An even simpler way to view your changes is using the git diff command.

Submitting the PR

Once you are happy with your commit you need to push them to your own fork so you can make a pull request. Unless this is your first single commit for the PR, you would want to squash them into one by running:

gaia$ git rebase -i master

That will take you through an interactive rebase and let you specify a new commit message. Give the commit an appropriate message such as “Bug 873574 proposed fix r=person_to_review”. One thing to note is that when you update your PR, you can completely update the commit message. Use rebase to keep your PR to only one commit, so it is nice and clean for the reviewers. Keep your commit message short and relevant. The commit message should have the bug number and a brief description of what you have done to fix it. Once the rebase is done, we can push the changes to our remote branch. First time around that branch is used to send a pull request to upstream gaia. That same branch is used later on to send subsequent updates to the PR.

gaia$ git push origin bug-873574-alarm-scroll -f

Asking for review

The primary channel to request review for gaia patches seems to be the bugzilla issue. Git does not integrate smoothly with bugzilla and linking to PR involves a bit of manual process. From what I understand, it is a convention to attach a small html file to the bug report containing a link to your pull request. Make sure to choose the file type as text/html. Here is what I used based on examples I saw in other bug reports:

<!DOCTYPE html>
<meta charset="utf-8">
<meta http-equiv="refresh" content="1;https://github.com/mozilla-b2g/gaia/pull/10336/">
<title>Bugzilla Code Review</title>
<p>Redirecting to <a href="https://github.com/mozilla-b2g/gaia/pull/10336/">» pull request on github</a></p>

I learnt that you can specify someone to review your PR right from the commit message, but I dont know if it is actually being used. As someone who is totally new to the project, it is bit hard to guess who would be an appropriate person to ask for review. One way to find out is to use the git blame on the areas of the code that you have changed and find out who has worked on it recently. Another way that was suggested to me is to choose someone from owners and peers for the Gaia module. When you are attaching the above html file, you get a chance to enter the name of that person in a review tag, make sure to take advantage of that.

I submitted my first PR to Gaia. Woot woot! 🙂

Updating the PR

Yup, it was not perfect ;). Chances are, you may also get a request to update your PR with some changes. PR is often a starting point for discussion about a fix. I received some comments from the UX team to change the fade color as well as some other comments about the code. I checked out my branch for that bug fix again and made those changes — making sure to rebase the commits after each update, so the PR remains with one commit.

Now I wait — patiently

One thing about trying to contribute to a very active project such as Gaia is that you may not always get a quick feedback or review. At the time I submit my PR there was nearly 390 open PRs already in the project. I have been told that most of those are stalled, but I think it still shows that the core team has a lot to process. Since the bug I chose is not a high priority, the fix most likely will not make the cut for next release, but hopefully will be pulled in after v1 is shipped. Gaia is still a young project and it is very exciting time to join in and contribute.

Thank You

Several people both on #gaia irc channel and local mozillians in Vancouver have helped me with the various steps along the way. I specially want to thank James Burke who guided me through flashing my phone with latest version of B2G and gave me a lot of great advice about working with Gaia and Javascript development in general.

Closing

As a frontend developer who is very excited about developing apps for Firefox OS platform, I want to learn the secrets and successful patterns for developing apps that look sharp and perform well. Tutorials, guides and documentations are very useful, but why would I want to go there if I can get what I am looking for directly from the source — the Gaia project that is. If you have not done so already, I encourage you to give it a shot and see if you can make a difference while you learn a few cool tips and tricks. I look forward to your comments and suggestions.

View full post on Mozilla Hacks – the Web developer blog

VN:F [1.9.22_1171]
Rating: 0.0/10 (0 votes cast)
VN:F [1.9.22_1171]
Rating: 0 (from 0 votes)

Hacking Gaia for Firefox OS, part 1

So I guess pretty much everyone is aware of this awesome new product being developed at Mozilla that is making a lot of noise in the mobile world. I am of course referring to FirefoxOS (code named Boot2Gecko) and if you have not heard of it yet, then you need to head over to the product page right now and also, the Wiki for a more technical overview.

Not to go into too much detail and restate what is already on the wiki, FirefoxOS is made up of three distinct parts:

  • Gonk – The ‘OS’ i.e. low level Linux kernel and hardware abstraction layer (HAL)
  • Gecko – The application runtime, also present in your desktop and mobile Firefox
  • Gaia – The user facing front end of the OS

Contributing to Gaia

As a front-end engineer this new OS opens a world of new possibilities but, did you know, you can also be part of and contribute to Gaia? This is true, and starting today I will be writing a series of posts on how you can get involved. Today’s topic is how to get a working environment that enables you to work on, test and contribute to Gaia. Ok then, let’s get started.

First thing right out of the door is to head over to Github and fork and clone the Gaia repo.

git clone git://github.com/yourusername/gaia.git &amp;&amp; cd gaia

After the above is complete, you are ready to make your local Gaia profile. Inside the gaia directory, which you should be in now, run:

DEBUG=1 make

The process above is going to do a bunch of things and the first time you run it, it is going to take some time so my suggestion is, take a break and make yourself some coffee. Once the above has completed the last line of output should be something like:

Profile Ready: please run [b2g|firefox]
-profile /Users/schalkneethling/mozilla/projects/gaia/profile

Downloading B2G desktop build

Keep a note of the -profile flag as you will need it in a minute. Next we need to download a B2G desktop build. For work on version 1 of Gaia, which is the current focus, we are going to be using the Aurora builds, on the linked FTP page, select the latest build for your platform and once downloaded, follow the usual process for installing an application on your environment.

Note: Due to some changes in the way events are sent and handled by apps the most recent builds of the B2G desktop will not work. To get around this, and ensure a more stable dev environment, you can make use of the builds from http://ftp.mozilla.org/pub/mozilla.org/b2g/nightly/latest-mozilla-b2g18/

Now that we have our profile and desktop build, let’s join the two. Open up a terminal (command line) and enter the following:

/path/to/b2g-bin -profile /path/to/profile
 
# Note: On Mac the path is slightly different as b2g-bin lives 
# inside the Contents folder of the .app so here use:
 
/path/to/b2g/B2G.app/Contents/MacOS/b2g-bin
-profile /path/to/gaia/profile

Set-up app

Once you run the above, a window will open up sized to the dimensions of the current FirefoxOS target device device and the set-up app will be will be visible. Click through this and complete as needed. After this, there will be a phone tour app loaded which you can either follow or skip.

Screen shot of a running B2G Desktop

NOTE: Currently there is a bug in the desktop build and once you exit the tour, you will be presented with a black screen. To get to the lock screen you will need to close down B2G (Ctrl+C should do it) and relaunch.

Making changes to the code

Once you have clicked around the interface a little, let’s look at making a simple change to one of the current apps and see our change reflected.

With B2G running, open up the Calendar app, it should be located on the third screen to the right of Home, on the top left. At the bottom you will see the usual triggers for displaying the calendar by month, week or day. Now in your editor of choice open up the index.html file inside gaia > apps > calendar

Screen shot of FirefoxOS showing calendar app icon

At around line 180 you will see the HTML that reflects the tabs I just referred to. Go ahead and completely remove the <menu> element and save the file.

<code>
<menu id="view-selector">
  <li class="today">
    <a href="#today">Today</a>
  </li>
  <li class="time-selection">
  ...
</code>

Next, without rebuilding Gaia, simply close B2G and relaunch. Now open up the calendar app again and this time you will see that the tabs from before are gone as expected. Great! Now go back and undo your changes and relaunch B2G and the calendar app again. Your tabs should now be back and working as before. This shows a simple example of a common workflow when developing with B2G desktop.

Debugging

One of the things that is tricky within this environment is debugging but, we are not left with nothing. If you start-up B2G as before but append the -jsconsole flag, you will now see that the error console you know from Firefox, open up alongside it. This is useful when you want to check for script errors or log messages out to the console.

Screen shot of B2G desktop running with jsconsole

Just to see how this will work, open up the month.js file inside gaia > apps > calendar > js > views and after the first line add:

console.log("Test log message when loading the Calendar App....");

Save the change and launch B2G with the -jsconsole flag. Once launched, click on the messages tab of the error console and then go ahead and open up the calendar app, you should now see your message printed.

NOTE: If you do not see your messages being logged to the console it might because console logging has been disabled. To remedy this, head to the Settings app on FirefoxOS, then Device Information > More Information > Developer > Console Enabled.

This then concludes the first post in this series but before ending the post, here are some useful places to get info and speed up development:

View full post on Mozilla Hacks – the Web developer blog

VN:F [1.9.22_1171]
Rating: 0.0/10 (0 votes cast)
VN:F [1.9.22_1171]
Rating: 0 (from 0 votes)