Updating your Geeksphone to the latest images

Firefox OS updates can be be downloaded from within the the Settings app, listed under Device information. The phone can be set to check for updates daily, weekly or monthly. In addition a “check now” button is provided. When an update is available you will be prompted to download and install the current version.

The team at Geeksphone is also now providing the latest stable and nightly builds as self contained downloads for flashing your phone. Before proceeding make you have setup your phone as described in “Setting Up the Geeksphone Device” section of the Pushing Firefox OS Apps to the Geeksphone post. This will insure that you can push data to the phone.

The builds are located at the Geeksphone download site. On this site you will be presented with options for selecting your device and what type of build you want to use.

Download your particular build and extract the archive to your filesystem. The archive contains the images and commands required to flash the phone using Windows, Mac OS X or Linux. Before attempting to flash the phone make sure that you have enabled Remote debugging on the phone. This option can be set by launching the Settings app and navigating to Device information -> More information -> Developer tab. Also do not attempt to flash the phone if the power level is below 50%.

Windows

Open a Command Prompt (start -> type cmd in search -> enter on windows 7, Windows key + X -> select Command Prompt on Windows 8) and cd to the directory containing the extracted files. Run:

flash.bat.

Mac OS X

Open a Terminal (Cmd + space -> type terminal -> enter) window and cd to the directory containing the extracted files. Run:

./flash_mac.sh

Linux

Open a Terminal (control-alt-t on Ubuntu) window and cd to the directory containing the extracted files. Run:

./flash.sh

This should flash the new image to the phone. The phone will need to be setup again as all data will be cleared.

Tweaking Gaia

If you are of the industrious sort, you may want to tweak the default applications in Gaia – the UI in Firefox OS. In this section we will cover some of the basics for cloning Gaia and making changes to the default system apps. Bear in mind these tips are “at your own risk” and may involve you reading the later section “Ok, I bricked my phone”. Before proceeding make sure that you have adb and fastboot installed on your system. To verify if these are installed open a terminal and type adb devices with your phone connected. You should see something similar to the following.

You should also be able to run fastboot from the terminal. If you run fastboot, a set of parameter options should be displayed. If you do not have adb or fastboot installed, a quick Google search with your operating system will return several quick starts on how to install them. In addition to adb and fastboot you will need Git. If you do not currently have Git installed have a look at this setup guide. Finally make sure your phone is setup for remote debugging as described in the previous section.

Once you have the prerequisites you can open a terminal and cd to the directory you would like to clone the Gaia source code to and type the following commands.

git clone git://github.com/mozilla-b2g/gaia.git gaia
cd gaia

This will clone the current Gaia code to your system. Currently the Geeksphone Keon uses the v1.0.1 branch of Gaia code, so set the proper branch using the following command.

git checkout -b v1.0.1 origin/v1.0.1

Most of the system apps are located in the apps subdirectory of gaia. You can now make any changes to these Firefox OS apps you wish. Once you have made changes run the following command to push the modified apps to your phone. This will by default push all the system apps to the phone:

B2G_SYSTEM_APPS=1 make install-gaia

If you only changed one of the apps you can specify the particular app using similar syntax. In this example only the calendar app will be pushed to the phone:

APP=calendar B2G_SYSTEM_APPS=1 make install-gaia

If you have issues while making the changes, you can reset the phone to default values using either of the following commands.

make production
make reset-gaia

Note: Bear in mind that either of the above commands will clear any data or apps that you have pushed to the phone.

“Ok, I bricked my phone”

If you are in the process of modifying your phone and it becomes “unresponsive” you should be able to recover it using fastboot with a simple procedure. The following illustrates reseting the Keon but other phones should have a similar process. You will also need to verify that you have fastboot installed.

First remove the USB cable and then remove the battery from the phone for thirty seconds. Then reinsert the battery and press the volume down button while holding the power button for a few seconds. Next re-connect the usb cable and run the following commands from a terminal window in the directory that contains the latest img files described in the first section of this post.

fastboot flash recovery recovery.img
fastboot flash boot boot.img
fastboot flash userdata userdata.img
fastboot flash system system.img
fastboot reboot

This process should recover your phone.

Go play!

We hope these instructions are useful to you, and naturally we want you to be as happy about Firefox OS and the possibilities as we are! Feel free to play around with updating your devices, making changes/updates to Gaia apps and also to be inspired to take these learnings into building your own Open Web Apps.

We’re also challenging you on the mobile front—with more than 10 million people using Firefox for Android, this is your chance to take the fun and personalization of add-ons to a fast-growing and passionate fan base.

A panel of judges will pick the best add-on from each prize category, and the community will choose which category winner is the best overall add-on. Category winners will receive Android tablets, and the Best Overall winner will receive an 11-inch Macbook Air. All participants whose entry is approved (fully reviewed) for AMO will receive “Amp Your Firefox” t-shirts! The winning add-ons will also get tons of exposure on AMO and other Mozilla properties.

The Categories

Best Mobile Add-on

Create add-ons that take Firefox for Android to the next level for over 10 million users by improving readability, enhancing the web experience across devices, and rounding out browsing features—get creative!

Best Mobile Add-on Port

If you’ve created an add-on for desktop and think it would be great for a mobile audience, port it over to Firefox for Android!

Best Game Add-on

It takes creativity and imagination to make a great game add-on like Cheevos or Destroy the Web—are you up for taking the challenge?

Best Complete Theme

Complete themes can dramatically change the look of your Firefox—everything from buttons, window frames, tabs, and menus can be customized—the sky’s the limit. Create complete themes that are both aesthetically pleasing and transform the appearance of Firefox.

Best Updated Add-on

If you’ve created an add-on and want to freshen it up by adding new features, making it restartless, or porting it to the SDK, this is the category for you.

Mobile Next!

One of the key categories we’re excited about for this competition is Mobile. Firefox for Android has done incredibly well in terms of user uptake and reviews in the Play marketplace, and the Android and Jetpack teams have both been working hard to make developing Add-ons for Mobile Firefox as easy as possible. Having said that, developing mobile add-ons is different enough that we thought we’d call out some of the highlights.

NativeWindow & BrowserApp

NativeWindow and BrowserApp are privileged JavaScript APIs that allow developers to add their own custom functionality to the Native Java UI that is used on Firefox for Android instead of XUL. BrowserApp provides add-on developers the ability to interact with mobile browser tabs. NativeWindow allows developers to add menu items to the main and context menus, and to trigger native notifications.

Mark Finkle has created a handy github repo that includes all of the boilerplate code you’ll need to get started. Using this restartless add-on skeleton as the basis for your work, NativeWindow and BrowserApp are easy to access as properties off of the window object:

// show a toast immediately
aWindow.NativeWindow.toast.show("Showing you a toast", "short");
 
// add a menu item that shows a toast when clicked
let menuId = aWindow.NativeWindow.menu.add(“Hello!”, icon, function() {
    aWindow.NativeWindow.toast.show("I ran the callback!", "short");
});

Jetpack – mobile ready

If you’re more comfortable with the Add-on SDK, I’m happy to report that the Jetpack team has done a lot of work to support mobile development. Most ( but not all ) Jetpack APIs work on Mobile, and the cfx command-line tool has been enhanced to be able to easily push your add-on onto the device for testing.

It is relatively simple to use NativeWindow from a Jetpack-based add-on:

// get the most recent window
const utils = require('api-utils/window/utils');
const recent = utils.getMostRecentBrowserWindow();
 
// show a toast notification
recent.NativeWindow.toast.show(opts.message, duration);
 
// listen for tabs events
let tabs = require('tabs');
tabs.on('ready', function(tab) {
    console.log(recent.BrowserApp.selectedTab.id, tabs.activeTab.id);
});

Caveats

Mobile phones present unique challenges for web browsers like Firefox mobile, so there are some very real limitations on what you can do with extensions as compared to desktop Firefox:

• Add-on Builder does not support packaging or running extensions on a phone
• Firefox for Android does not support XUL overlays
• not all of the Add-on SDK’s modules are compatible with Firefox for Android, please consult this compatibility guide for more information.

For even more detail on using the NativeWindow api and Jetpack for hacking on mobile extensions, see the Jetpack, Fennec and NativeWindow blog post in the Mozilla Add-ons blog.

Get going!

• See complete contest details on the AMO blog
• See tutorials, articles, and connect with add-on developers in the Developer Community and Developer Hub
• See articles on developing extensions for Firefox on Android

Have fun, and good luck!

New content

Mixed security content blocking is now turned on by default in Firefox Aurora. David Bruant and Xavier Borderie improved the Mixed content page and David created How to fix a website with blocked mixed content.

Jérémie Patonnier hosted the meet-up in the Paris office, and finished documenting the WebFM API. Jérémie has been documenting lots of the hardware device APIs. Check out this Device orientation example, if your browser and device support it.

New contributor Scott Turner improved the Using IndexedDB article.

Translations

A sprint meet-up in Mozilla’s Paris office meant that lots of French translation work got done, with lots of fixes to the corresponding English content along the way. Several people continued working after the end of the sprint, so by now:

• All HTML element reference pages are translated into French! Thanks to Thierry Régagnon, Dorian Jamiais, Sphinx, mistyrouge and others who helped along the way.
• Jeremy Fourna translated several API pages into French: AnimationEvent, Attr, AudioBuffer, AudioBufferSourceNode
• Thierry and Jean-Bernard (“Goofy”) Marcon started translating the HTML forms guide into French.
• Jesus Perez translated several Apps and Firefox OS docs into Spanish, which are very much needed to support the Firefox OS launch.

Reviews

William Reynolds completed editorial reviews on a large number of articles, from Rhino Runtime to Object defineProperty.

Editorial reviews (checking grammar, spelling, etc.) are a quick and easy way to contribute to MDN, even if you’re new to development. Lots of newcomers to MDN start out by doing editorial reviews — you can too! Just click Sign in on any MDN page, and create an account via Mozilla Persona.

Using this knowledge, I thought it’d be fun to create a small game I saw in an ad for a tablet: a simple game for kids to paint letters. The result is a demo for FirefoxOS called Letterpaint which will show up soon on the Marketplace. The code is on GitHub.

The fun thing about building Letterpaint was that I took a lot of shortcuts. Painting on a canvas is easy (and gets much easier using Jacob Seidelin’s Canvas cheatsheet), but on the first glance making sure that users stay in a certain shape is tricky. So is finding out how much of the letter has been filled in. However, by going back to seeing a Canvas as a collection of pixels, I found a simple way to make this work:

• When I paint the letter, I read out the amount of pixels that have the colour of the letter
• When you click the mouse button or touch the screen I test the colour of the pixel at the current mouse/finger position
• When the pixel is not transparent, you are inside the letter as the main Canvas by default is transparent
• When you release the mouse or stop touching the screen I compare the amount of pixels of the paint colour with the ones of the letter.

Simple, isn’t it? And it is all possible with two re-usable functions:

/*
  getpixelcolour(x, y)
  returns the rgba value of the pixel at position x and y
*/
function getpixelcolour(x, y) {
  var pixels = cx.getImageData(0, 0, c.width, c.height);
  var index = ((y * (pixels.width * 4)) + (x * 4));
  return {
    r: pixels.data[index],
    g: pixels.data[index + 1],
    b: pixels.data[index + 2],
    a: pixels.data[index + 3]
  };
}
 
/*
  getpixelamount(r, g, b)
  returns the amount of pixels in the canvas of the colour 
  provided
*/
function getpixelamount(r, g, b) {
  var pixels = cx.getImageData(0, 0, c.width, c.height);
  var all = pixels.data.length;
  var amount = 0;
  for (i = 0; i < all; i += 4) {
    if (pixels.data[i] === r &&
        pixels.data[i + 1] === g &&
        pixels.data[i + 2] === b) {
      amount++;
    }
  }
  return amount;
}

Add some painting functions to that and you have the game done. You can see a step by step guide of this online (and pull the code from GitHub) and there is a screencast describing the tricks and decisions on YouTube.

The main thing to remember here is that it is very tempting to reach for libraries and tools to get things done quickly, but that it could mean that you think too complex. Browsers have very powerful tools built in for us, and in many cases it means you just need to be up-to-date and fearless in trying something “new” that comes out-of-the-box.

What it is

The API is about detecting how close the device is to any other physical object, by accessing the proximity sensor. There are two ways of working with proximity

• Device proximity
• User proximity

From the spec:

The DeviceProximityEvent interface provides web developers information about the distance between the hosting device and a nearby object.

The UserProximityEvent interface provides web developers a user-agent- and platform-specific approximation that the hosting device has sensed a nearby object.

Using it

Working with proximity is as easy as adding a couple of event handlers, depending on what you want to do. The deviceproximity event works with the metric system, and you will get back the distance in centimeters (these examples take for granted that you have an existing proximityDisplay element to present the values in). You are also able to check the minimum and maximum distance the sensor in your device supports.

window.ondeviceproximity = function (event) {
    // Check proximity, in centimeters
    var prox = "<strong>Proximity: </strong>" + event.value + " cm<br>";
        prox += "<strong>Min value supported: </strong>" + event.min + " cm<br>";
        prox += "<strong>Max value supported: </strong>" + event.max + " cm";
    proximityDisplay.innerHTML = prox;
};

It should be noted that the values sensors currently can return a quite small value, ranging from 0 up to 5 or 10 centimeters. In general, I believe the use case has been to detect if the user is holding the device up to the ear or not, but my personal opinion is that this could provide to be even more exciting if it supported, say, up to a meter!

With userproximity, the value you get back is a near property on the event object, which is a boolean returning whether the user is near to the sensor or not.

window.onuserproximity = function (event) {
    // Check user proximity
    var userProx = "<strong>User proximity - near: </strong>" + event.near + "<br>";
    userProximityDisplay.innerHTML = userProx;
};

I’ve also added device and proximity code and testing to the Firefox OS Boilerplate App so feel free to get the latest code there and play around with it.

Web browser support

The Proximity API is currently supported in:

• Firefox OS
• Firefox on Android

Conclusion

Working with proximity is yet another example of crossing the gap between software and real physical context, and showing just how powerful the web can be. We hope to see you creating many interesting things based on it!

The source for the Todo app is available on GitHub.

Setting Up the Environment

We will use volo as our package manager and build tool.

Step 1

First you need to install Node.js because volo depends on it. Windows and Mac users can download it from here. But for Linux users, I recommend you use the package manager: instructions for installation using package manager on different distros.

Step 2

Install volo using the following command.

npm install -g volo

Make sure you use `sudo` before above command in *nix environment.

Step 3

Create a blank project fos-todo-app using `volo create` command.

volo create fos-todo-app

This will create a folder fos-todo-app and copy required volo project files from GitHub.

Remember we will work only with the files in fos-todo-app/www directory. If you have never worked with volo before, [Streamline your Process with Volo](http://net.tutsplus.com/tutorials/javascript-ajax/streamline-your-process-with-volo/) is a recommended read.

Step 4

Make sure you have the latest stable version of Firefox installed. Then [install the Firefox OS simulator add-on](https://addons.mozilla.org/en-US/firefox/addon/firefox-os-simulator/). At the end of this article we will test UI of our app in this simulator.

Step 5

Get the [MozTT font](https://github.com/mozilla-b2g/moztt/tree/master/MozTT) and install it. MozTT is the font used in Firefox OS. It’s an optional step but it’s better to install this font on your system so you can get consistent look and feel in the Firefox OS Simulator and the real phone.

Todo View

The first UI that we will build will show a title in the header, Add/Delete buttons in the footer and a todo list. This view will be used for viewing, editing, mark as complete, and deleting tasks.

Add role="application" attribute to the `body` element and write following HTML for the Todo View.

<section id="view-todos" role="region">
  <header>
    <h1>Todos</h1>
  </header>
 
  <article class="view-content">
    <ul id="todo-list" class="todo-list reset-list" role="list">
      <li role="listitem">
        <label>
          <input type="checkbox">
          <span>My task 1</span>
        </label>
 
        <input type="text" aria-hidden="true">
        <button class="btn edit"><span>Edit</span></button>
      </li>
 
      <li role="listitem">
        <label>
          <input type="checkbox" checked>
          <span>My task 2</span>
        </label>
 
        <input type="text" aria-hidden="true">
        <button class="btn edit"><span>Edit</span></button>
      </li>
    </ul>
  </article>
 
  <footer>
    <menu role="toolbar">
      <button role="menuitem" class="btn add"><span>Add</span></button>
      <button role="menuitem" class="btn del" disabled><span>Delete</span></button>
    </menu>
  </footer>
</section><!--end view-todos-->

Each view is assigned a role="region". Within the view, you can have header, footer and any container element having the view-content class which will contain the contents of the view.

In the above view’s content, we have ul[role=list] which contains tasks entered by user. For testing purposes, I added two dummy tasks so you can understand each list item’s (`li[role=listitem]`) structure. Within each list item we have a label element containing a <input type="checkbox"> and a span element containing the text of task. The second element in the list item contains a <input type="text"> element which is initially hidden using attribute aria-hidden="true". Finally the third element is .btn.edit (edit button).

Note: Of course it’s not magic. We will write CSS for all these attributes. Check out ARIA and Progressive Enhancement if you are new to WAI-ARIA.

The purpose of placing the label in the list item is to display each task’s text and input[type=text] (which is initially hidden) will be used to edit that text. Any task can enter edit mode when user tap on .btn.edit (edit button). Similarly, tasks are “marked as completed” when user tap on label.

In the footer we have menu[role=toolbar] containing Add/Delete buttons. Later using CSS for these buttons, we will display a svg icon in background and hide an inner span in it.

Add View

The second and final view in our app will be used to add tasks to the todo list.

In this view we have a textbox for entering a task’s text, and a insert contact link will be used to add the contact number using Web Activities. Here’s the HTML for Add View.

<section id="view-add" role="region">
  <header>
    <h1>[+] Todo</h1>
  </header>
 
  <section class="view-content">
    <div class="wrapper">
      <menu class="options">
        <ul id="activities" class="reset-list" role="list">
          <li role="listitem"><a href="#"><label for="task">[Insert Contact]</label></a></li>
        </ul>
      </menu>
 
      <form aria-owns="btn-add-done">
        <input type="text" name="task" id="task" required>
      </form>
    </div>
  </section>
 
  <footer>
    <menu role="toolbar">
      <button id="btn-add-done" role="menuitem" class="btn done" disabled><span>Done</span></button>
      <button role="menuitem" class="btn del"><span>Cancel</span></button>
    </menu>
  </footer>
</section><!--end view-add-->

Note that the contents in section.view-content is wrapped using div.wrapper so we can limit its max-width and right align menu.options.

Second thing to note here is the aria-owns attribute on form element. This attribute relates to the form with btn-add-done.

Element Styles

Let’s write the CSS for the HTML elements. An explanation is given in comments above each selector.

/* Stretch vertically */
html, body { height: 100%; }
 
body {
  background: radial-gradient(ellipse at center, rgba(231,76,60,1) 0%,rgba(192,57,43,1) 100%);
  color: #fff;
  font-family: MozTT, sans-serif;
 
  /* Reset base size */
  font-size: 16px;
 
  /* Set font size relative to base size */
  /* Check <a href="http://snook.ca/archives/html_and_css/font-size-with-rem">this</a> article on rem usage */
  font-size: 1.4rem;
 
  font-weight: 300;
 
  /* Remove spacing */
  margin: 0;
}
 
h1, h2, h3, h4, h5, h6 { font-weight: 300; }
 
h1 { font-size: 3rem; }
 
a {
  color: #FFA49E;
  text-decoration: none;
  text-shadow: 0px 1px 1px rgba(0,0,0,.3);
}
a:hover { color: #fff; }
 
input, button, select, textarea {
  border-radius: 0;
  box-shadow: none;
}
input[type=text], textarea, select {
  border: none;
  font-family: MozTT, sans-serif;
  font-size: 1.3rem;
  font-weight: 300;
  padding: .7rem .8rem;
}

View Specific Styles

#view-todos > .view-content {
  margin-left: 0;
  margin-right: 0;
}
 
#view-add > .view-content {
  margin-top: 2rem;
}
#view-add > .view-content > .wrapper {
  overflow: hidden;
  margin: 0 auto;
  max-width: 800px;
  width: 100%;
}
#view-add input[name=task] {
  width: 100%;
}
#view-add .options {
  margin: 0 0 .5rem 0;
  text-align: right;
}
#view-add .options [role=listitem] {
  margin: .5rem 0;
}
#view-add .options a {
  padding: .4rem;
}

Module Styles

View Module

/* All views have region role so selecting them with attribute selector  */
[role=region] {
  background: radial-gradient(ellipse at center, rgba(231,76,60,1) 0%,rgba(192,57,43,1) 100%);
 
  /* Stretch both vertically/horizontally */
  top: 0; right: 0; bottom: 0; left: 0;
 
  position: fixed;
  overflow-x: hidden;
}
[role=region] > header {
  margin: .5rem 0 1rem 0;
  text-align: center;
}
[role=region] > header > h1 {
  margin: 0;
  text-shadow: 0px 1px 1px rgba(0,0,0,.4);
}
[role=region] > .view-content {
  margin: 0 1rem 4rem 1rem;
}
[role=region] > footer {
  background: rgba(0,0,0,.2);
  right: 0; bottom: 0; left: 0;
  position: fixed;
  text-align: center;
}
[role=region] > footer > menu[role=toolbar] {
  margin: 0;
  padding: 0;
}

Button Module

.btn {
  border: none;
  width: 3.5rem;
  height: 3.5rem;
}
.btn > span {
  display: none;
}
.btn:disabled {
  opacity: .2;
}
.btn.done {
  background: url(../img/check.svg) no-repeat center center;
}
.btn.add {
  background: url(../img/add.svg) no-repeat center center;
}
.btn.del {
  background: url(../img/del.svg) no-repeat center center;
}
.btn.edit {
  background: url(../img/edit.svg) no-repeat center center;
}
.btn:hover {
  background-color: rgba(255,255,255,.1);
}

Todo List Module

.todo-list > li {
  border-bottom: 1px solid rgba(255,255,255,.1);
  position: relative;
}
.todo-list > li > .btn {
  top: 0; right: 0;
  position: absolute;
  height: 3.9rem;
}
.todo-list label {
  border-bottom: 1px solid rgba(0, 0, 0, 0.1);
  display: block;
  padding: 1rem 2.8rem 1rem 1rem;
}
.todo-list > li:last-child,
.todo-list > li:last-child > label {
  border-bottom: none;
}
.todo-list label > span {
  transition: all .5s;
}
 
/***
  This selector is interesting. It creates a line-through and
  decrease opacity of text in span when checkbox is checked
***/
.todo-list input[type=checkbox]:checked + span {
  text-decoration: line-through;
  opacity: .4;
}
 
.todo-list > li > input[type=text] {
  margin: .4rem;
  /* removing input padding and margin from 100% */
  width: calc(100% - 2.3rem);
}

Utility Styles

.reset-list {
  list-style: none;
  margin: 0;
  padding: 0;
}
[aria-hidden=true] {
  display: none !important;
}

Animations

Following are a few animation effects that we will use to animate our views. Although we will use Zepto.js which on run-time generates CSS3 animations using JavaScript, I prefer to write my own animations using CSS3 and make use of it by applying/removing CSS classes on DOM elements.

Zepto is a minimalist JavaScript library for modern browsers with a largely jQuery-compatible API. If you use jQuery, you already know how to use Zepto. ‐ zeptojs.com

Check out the How to use CSS Animations tutorial for understanding CSS3 Animations better.

.slide-up-in {
  animation-name: slide-up-in;
  animation-duration: .6s;
  transform: translateY(0%);
  opacity: 1;
}
@keyframes slide-up-in {
  0% { transform: translateY(30%); opacity: 0; }
  100% { transform: translateY(0%); opacity: 1; }
}
 
.slide-down-out {
  animation-name: slide-down-out;
  animation-duration: .6s;
  transform: translateY(30%);
  opacity: 0;
}
@keyframes slide-down-out {
  0% { transform: translateY(0%); opacity: 1; }
  100% { transform: translateY(30%); opacity: 0; }
}
 
.slide-right-in {
  animation-name: slide-right-in;
  animation-duration: .6s;
  transform: translateX(0%);
}
@keyframes slide-right-in {
  0% { transform: translateX(-100%); }
  100% { transform: translateX(0%); }
}
 
.slide-left-out {
  animation-name: slide-left-out;
  animation-duration: .6s;
  transform: translateX(-100%);
}
@keyframes slide-left-out {
  0% { transform: translateX(0%); }
  100% { transform: translateX(-100%); }
}

Testing in Firefox OS Simulator

You can pretty easily test the UI we have developed using the Firefox OS Simulator. All you need is a manifest.webapp file in root directory (fos-todo-app/www). Add the following json in it.

{
  "version": "0.1",
  "name": "Todos",
  "description": "Awesome todo app by iFadey",
  "launch_path": "/index.html",
  "icons": {
    "16": "/img/icons/icon-16.png",
    "48": "/img/icons/icon-48.png",
    "128": "/img/icons/icon-128.png"
  },
  "developer": {
    "name": "Fawad Hassan",
    "url": "http://ifadey.com"
  },
  "installs_allowed_from": ["*"],
  "appcache_path": "/cache.manifest",
  "default_locale": "en"
}

Currently I haven’t added an app icon but don’t worry about it. Firefox OS adds a default app icon if it doesn’t find one mentioned in the manifest file. Now open the simulator tab from Tools > Web Developer > Firefox OS Simulator. Then click Add Directory button and select the manifest file from our app directory. This will add our app in the simulator.

End of part 1

Now you have gotten started with the Todo app and have gotten going with a few easy steps. In next part we will add life in our app using JavaScript (Backbone/Zepto). We will create Todo model, collection, and views and for the sake of simplicity, we will only store our todo collection in IndexedDB. We will also make use of Web Activities to inject contact number in text of todo task.

Over on the Mozilla Developer Network site, this Friday and Saturday (May 31 and June 1), we’re having the latest in our series of “MDN sprints”. This is a chance for you to learn about a web development topic, and help improve the resources about it on MDN by sharing what you learn or what you already know. Please join us!

About what?

The major topical focus for this sprint is Web device APIs, which give JavaScript code access to device hardware. How about trying them out, and then writing some helpful code examples?

Another timely topic is mixed content blocking, which just arrived in the Firefox Aurora channel. Help us explain to Web developers how to fix sites so users won’t be tripped up by mixed-security content.

But those are just suggestions; any topic for Web developers or Mozilla developers is fair game. You can also find more info and ideas on the MDN sprint wiki page.

Where?

You can join in from anywhere in the world. Of course you could just dive into MDN, but part of the point of a sprint is to do it with other people. Join the #devmo channel on irc.mozilla.org to talk with other sprinters, about what you’re doing, they’re doing, or whatever. (Here’s info about IRC if you’re not familiar with it.) We might also do a Google Hangout, so ask about that when you drop in.

If you happen to be in San Francisco or Paris, we’re holding in-person meetups for this sprint on June 1st, at the Mozilla spaces in those cities. Come on by and sprint in person!

• San Francisco meetup page on Lanyrd
• Paris meetup page on Lanyrd

When?

The sprint officially runs from 8:00 a.m. PDT on May 31st (Starting time in your timezone) to 5:00 p.m. PDT on June 1st (Ending time in your timezone). Of course, you can start earlier or continue later, and stay for as long or as short a time as fits your schedule.

Sound interesting? Give it a try!

Making the best of 256 Mb RAM/800 Mhz CPU

There are many areas of focus to keep in mind while developing a game. When your goal is to draw 60 times a second, garbage collection and inefficient drawing calls start to get in your way. Let’s start with the basics…

Don’t over-optimize

This might sound counter-intuitive in an article about game optimization but optimization is the last step; performed on complete, working code. While it’s never a bad idea to keep these tips and tricks in mind, you don’t know whether you’ll need them until you’ve finished the game and played it on a device.

Optimize Drawing

Drawing on HTML5 2D canvas is the biggest bottleneck in most JavaScript games, as all other updates are usually just algebra without touching the DOM. Canvas operations are hardware accelerated, which can give you some extra room to breath.

Use whole-pixel rendering

Sub-pixel rendering occurs when you render objects on a canvas without whole values.

ctx.drawImage(myImage, 0.3, 0.5)

This causes the browser to do extra calculations to create the anti-aliasing effect. To avoid this, make sure to round all co-ordinates used in calls to drawImage using Math.floor or as you’ll reader further in the article, bitwse operators.

jsPerf – drawImage whole pixels.

Cache drawing in an offscreen canvas

If you find yourself with complex drawing operations on each frame, consider creating an offscreen canvas, draw to it once (or whenever it changes) on the offscreen canvas, then on each frame draw the offscreen canvas.

myEntity.offscreenCanvas = document.createElement(“canvas”);
myEntity.offscreenCanvas.width = myEntity.width;
myEntity.offscreenCanvas.height = myEntity.height;
myEntity.offscreenContext = myEntity.offscreenCanvas.getContext(“2d”);
 
myEntity.render(myEntity.offscreenContext);

Use moz-opaque on the canvas tag (Firefox Only)

If your game uses canvas and doesn’t need to be transparent, set the moz-opaque attribute on the canvas tag. This information can be used internally to optimize rendering.

<canvas id="mycanvas" moz-opaque></canvas>

Described more in Bug 430906 – Add moz-opaque attribute on canvas.

Scaling canvas using CSS3 transform

CSS3 transforms are faster by using the GPU. Best case is to not scale the canvas or have a smaller canvas and scale up rather than a bigger canvas and scale down. For Firefox OS, target 480 x 320 px.

var scaleX = canvas.width / window.innerWidth;
var scaleY = canvas.height / window.innerHeight;
 
var scaleToFit = Math.min(scaleX, scaleY);
var scaleToCover = Math.max(scaleX, scaleY);
 
stage.style.transformOrigin = "0 0"; //scale from top left
stage.style.transform = "scale(" + scaleToFit + ")";

See it working in this jsFiddle.

Nearest-neighbour rendering for scaling pixel-art

Leading on from the last point, if your game is themed with pixel-art, you should use one of the following techniques when scaling the canvas. The default resizing algorithm creates a blurry effect and ruins the beautiful pixels.

canvas {
  image-rendering: crisp-edges;
  image-rendering: -moz-crisp-edges;
  image-rendering: -webkit-optimize-contrast;
  -ms-interpolation-mode: nearest-neighbor;
}

or

var context = canvas.getContext(‘2d’);
context.webkitImageSmoothingEnabled = false;
context.mozImageSmoothingEnabled = false;
context.imageSmoothingEnabled = false;

More documentation is available on MDN for image-rendering.

CSS for large background images

If like most games you have a static background image, use a plain DIV element with a CSS background property and position it under the canvas. This will avoid drawing a large image to the canvas on every tick.

Multiple canvases for layers

Similar to the last point, you may find you have some elements that are frequently changing and moving around whereas other things (like UI) never change. An optimization in this situation is to create layers using multiple canvas elements.

For example you could create a UI layer that sits on top of everything and is only drawn during user input. You could create game layer where the frequently updating entities exist and a background layer for entities that rarely update.

Don’t scale images in drawImage

Cache various sizes of your images on an offscreen canvas when loading as opposed to constantly scaling them in drawImage.

jsPerf – Canvas drawImage Scaling Performance.

Be careful with heavy physics libraries

If possible, roll your own physics as libraries like Box2D don’t perform well on low-end Firefox OS devices.

When asm.js support lands in Firefox OS, Emscripten-compiled libraries can take advantage of near-native performance. More reading in Box2d Revisited.

Use WebGL instead of Context 2D

Easier said than done but giving all the heavy graphics lifting to the GPU will free up the CPU for greater good. Even though WebGL is 3D, you can use it to draw 2D surfaces. There are some libraries out there that aim to abstract the drawing contexts.

• gameclosure – webgl-2d
• GoodBoyDigital – pixi.js
• ThreeJS

Minimize Garbage Collection

JavaScript can spoil us when it comes to memory management. We generally don’t need to worry about memory leaks or conservatively allocating memory. But if we’ve allocated too much and garbage collection occurs in the middle of a frame, that can take up valuable time and result in a visible drop in FPS.

Pool common objects and classes

To minimise the amount of objects being cleaned during garbage collection, use a pre-initialised pool of objects and reuse them rather than creating new objects all the time.

Code example of generic object pool:

Avoid internal methods creating garbage

There are various JavaScript methods that create new objects rather than modifying the existing one. This includes: Array.slice, Array.splice, Function.bind.

Read more about JavaScript garbage collection

• High-Performance, Garbage-Collector-Friendly Code
• How to write low garbage real-time Javascript

Avoid frequent calls to localStorage

LocalStorage uses file IO and blocks the main thread to retrieve and save data. Use an in-memory object to cache the values of localStorage and even save writes for when the player is not mid-game.

Code example of an abstract storage object:

Async localStorage API with IndexedDB

IndexedDB is a non-blocking API for storing data on the client but may be overkill for small and simple data. Gaia’s library to make localStorage API asynchronous, using IndexedDB is available on Github: async_storage.js.

Miscellaneous micro-optimization

Sometimes when you’ve exhausted all your options and it just won’t go any faster, you can try some micro-optimizations below. However do note that these only start to make a difference in heavy usage when every millisecond counts. Look for them in your hot game loops.

Use x | 0 instead of Math.floor

• jsPerf – Math.floor vs Math.round vs parseInt vs Bitwise
• Bitwise Gems and other optimizations

Clear arrays with .length = 0 to avoid creating a new Array

Sacrifice some CPU time to avoid creating garbage.

Use if .. else over switch

jsPerf – switch vs if-else

Date.now() over (+ new Date)

jsPerf – Date.now vs new Date().getTime() vs +new Date

Or performance.now() for a sub-millisecond solution

Use TypedArrays for floats or integers (e.g. vectors and matrices)

gl-matrix – Javascript Matrix and Vector library for High Performance WebGL apps

Conclusion

Building for mobile devices and not-so-strong hardware is a good and creative exercise, and we hope you will want to make sure your games work well on all platforms!

We have just landed support for the Content Security Policy (CSP) 1.0
specification in Firefox Aurora (Firefox 23), available as of tomorrow (May 30th). CSP is a security mechanism that aims to protect a website against content injection attacks by providing a whitelist of known-good domain names to accept JavaScript (and other content) from. CSP does this by sending a Content-Security-Policy header with the document it protects (yes, we lost the X prefix with the 1.0 version of the spec).

To effectively protect against XSS, a few JavaScript features have to be
disabled:

• All inline JavaScript is disallowed. This means, that all the JavaScript code must be placed in a separate file that is linked via <script src=... >
• All calls to functions which allow JavaScript code being executed from strings (e.g., eval) are disabled

CSP now more intuitive and consistent

While Firefox has had support for CSP since its invention here at Mozilla, things have been changing a lot. The streamlined development of a specification within the W3C has made the concept more intuitive and consistent. Most directives in a CSP header are now of a unified form which explicitly specifies the type of content you want to restrict:

• img-src
• object-src
• script-src
• style-src and so on.

Oh and if you feel like you must allow less secure JavaScript coding styles, you can add the values unsafe-inline or unsafe-eval to your list of script sources. (This used to be inline-script and eval-script before).

Start protecting your website by implementing CSP now!

But wait – isn’t that a bit tedious… Writing a complex policy and making sure that you remembered all the resources that your website requires? Don’t fret! Here comes UserCSP again!

Generate your Content Security Policies with UserCSP!

During the last few months, Kailas Patil, a student in our Security Mentorship Program has continued his GSoC work from last year to update UserCSP.

UserCSP is a Firefox add-on that helps web developers and security-minded users use CSP. Web developers can create a Content Security Policy (CSP) for their site by using UserCSP’s infer CSP feature. This feature can list required resource URLs and turn them into a policy ready to plug into a CSP header.

In addition, UserCSP is the first step to expose a policy enforcement mechanism directly to web users. Furthermore, users can enforce a stricter policy than a page supplies through the add-on or apply a policy to certain websites that don’t currently support CSP.

While earlier versions of UserCSP were more aligned to content security policies as originally invented at Mozilla, this version is updated to be in compliance with the CSP 1.0 specification. This means that policies derived with this add-on may work in all browsers as soon as they support the specification. Hooray!

As this evolves and ships, our MDN documentation on Content Security Policy (CSP) will keep on evolving, and we also plan to write more about this in the Mozilla Security Blog in the next few weeks, so stay tuned!

This is a tutorial on how to write a compiler which generates JavaScript as its target language, and maintains line and column meta-data in source maps for debugging. Storing line and column coordinates in a source map allows the end-user of the compiler to debug the source code that they wrote, rather than the ugly, generated JavaScript they are not familiar with.

In this tutorial, we will be compiling a small Reverse Polish Notation, or RPN, language to JavaScript. The language is super simple, and is nothing more than simple arithmetic with variable storage and output capabilities. We are keeping the language simple so that we can focus on integrating source maps with the compiler, rather than language implementation details.

Availability

Initial support for source maps in the debugger is available in Firefox 23 (Aurora at time of writing) with more improvements coming in Firefox 24 (Nightly at time of writing). Chrome DevTools also have support for source maps.

Overview of the Source Language

RPN uses postfix notation, meaning that the operator follows its two operands. One of the benefits of RPN is that as long as we limit ourselves to binary operators, we do not need any parentheses, and do not need to worry about operator precedence.

Here is an example program in our source language:

a 5 =;
b 3 =;
c a b + 4 * =;

This is an equivalent program written in a language which uses infix notation for its arithmetic operators:

a = 5;
b = 3;
c = (a + b) * 4;

Our language will support addition, subtraction, multiplication, division, assignment, and printing. The print operator’s first operand is the value to print, the second operand is how many times to print the value and must be greater than or equal to one:

5 1 print;
# Output:
# 5
 
3 4 print;
# Output:
# 3
# 3
# 3
# 3
 
4 print;
# Syntax error
 
n -1 =;
4 n print;
# Runtime error

Lastly, division by zero should throw an error:

5 0 /;
# Runtime error

Getting Setup

We will be writing our compiler on Node.js, using Jison to generate the parser for our language from a grammar, and using the source-map library to help generate source maps.

The first step is to download and install Node.js if you don’t already have it on your system.

After you have installed Node.js, use its package manager npm to create a new project for the compiler:

$ mkdir rpn
$ cd rpn/
$ npm init .

After the last command, npm will prompt you with a bunch of questions. Enter your name and email, answer ./lib/rpn.js for the main module/entry point, and just let npm use the defaults that it supplies for the rest of the questions.

Once you have finished answering the prompts, create the directory layout for the project:

$ mkdir lib
$ touch lib/rpn.js
$ mkdir -p lib/rpn

The public API for the compiler will reside within lib/rpn.js, while the submodules we use to implement various things such as the lexer and abstract syntax tree will live in lib/rpn/*.js.

Next, open up the package.json file and add jison and source-map to the project’s dependencies:

...
"dependencies": {
  "jison": ">=0.4.4",
  "source-map": ">=0.1.22"
},
...

Now we will install a link to our package in Node.js’s globally installed packages directory. This allows us to import our package from the Node.js shell:

$ npm link .

Make sure that everything works by opening the Node.js shell and importing our package:

$ node
> require("rpn")
{}

Writing the Lexer

A lexer (also known as a scanner or tokenizer) breaks the inputted raw source code into a stream of semantic tokens. For example in our case, we would want to break the raw input string "5 3 +;" into something like ["5", "3", "+", ";"].

Because we are using Jison, rather than writing the lexer and parser by hand, our job is much easier. All that is required is to supply a list of rules that describe the types of tokens we are expecting. The left hand side of the rules are regular expressions to match individual tokens, the right hand side are the snippets of code to execute when an instance of the corresponding token type is found. These tokens will be passed on to the parser in the next phase of the compiler.

Create the rules for lexical analysis in lib/rpn/lex.js:

exports.lex = {
  rules: [
    ["\\s+",                   "/* Skip whitespace! */"],
    ["#.*\\n",                 "/* Skip comments! */"],
    [";",                      "return 'SEMICOLON'"],
    ["\\-?[0-9]+(\\.[0-9]+)?", "return 'NUMBER';"],
    ["print",                  "return 'PRINT';"],
    ["[a-zA-Z][a-zA-Z0-9_]*",  "return 'VARIABLE';"],
    ["=",                      "return '=';"],
    ["\\+",                    "return '+';"],
    ["\\-",                    "return '-';"],
    ["\\*",                    "return '*';"],
    ["\\/",                    "return '/';"],
    ["$",                      "return 'EOF';"]
  ]
};

Writing the Parser

The parser takes the tokens from the lexer one at a time and confirms that the input is a valid program in our source language.

Once again, the task of writing the parser is much easier than it would otherwise be thanks to Jison. Rather than writing the parser ourselves, Jison will programmatically create one for us if we provide a grammar for the language.

If all we cared about was whether the input was a valid program, we would stop here. However, we are also going to compile the input to JavaScript, and to do that we need to create an abstract syntax tree. We build the AST in the code snippets next to each rule.

A typical grammar contains productions with the form:

LeftHandSide → RightHandSide1
             | RightHandSide2
             ...

However, in Jison we are a) writing in JavaScript, and b) also providing code to execute for each rule so that we can create the AST. Therefore, we use the following format:

LeftHandSide: [
  [RightHandSide1, CodeToExecute1],
  [RightHandSide2, CodeToExecute2],
  ...
]

Inside the code snippets, there are a handful of magic variables we have access to:

• $$: The value of the left hand side of the production.
• $1/$2/$3/etc: The value of the the nth form in the right hand side of the production.
• @1/@2/@3/etc: An object containing the line and column coordinates where the nth form in the right hand side of the production was parsed.
• yytext: The full text of currently matched rule.

Using this information, we can create the grammar in lib/rpn/bnf.js:

exports.bnf = {
  start: [
    ["input EOF", "return $$;"]
  ],
  input: [
    ["",           "$$ = [];"],
    ["line input", "$$ = [$1].concat($2);"]
  ],
  line: [
    ["exp SEMICOLON", "$$ = $1;"]
  ],
  exp: [
    ["NUMBER",           "$$ = new yy.Number(@1.first_line, @1.first_column, yytext);"],
    ["VARIABLE",         "$$ = new yy.Variable(@1.first_line, @1.first_column, yytext);"],
    ["exp exp operator", "$$ = new yy.Expression(@3.first_line, @3.first_column, $1, $2, $3);"]
  ],
  operator: [
    ["PRINT", "$$ = new yy.Operator(@1.first_line, @1.first_column, yytext);"],
    ["=",     "$$ = new yy.Operator(@1.first_line, @1.first_column, yytext);"],
    ["+",     "$$ = new yy.Operator(@1.first_line, @1.first_column, yytext);"],
    ["-",     "$$ = new yy.Operator(@1.first_line, @1.first_column, yytext);"],
    ["*",     "$$ = new yy.Operator(@1.first_line, @1.first_column, yytext);"],
    ["/",     "$$ = new yy.Operator(@1.first_line, @1.first_column, yytext);"]
  ]
};

Implementing the Abstract Syntax Tree

Create the definitions for the abstract syntax tree nodes in lib/rpn/ast.js.

Since we will be maintaining line and column information in all of the AST nodes, we can reuse some code by making a base prototype:

var AstNode = function (line, column) {
  this._line = line;
  this._column = column;
};

The definitions for the rest of the AST nodes are pretty straight forward. Link up the prototype chain, assign relevant attributes, and don’t forget to call AstNode‘s constructor:

exports.Number = function (line, column, numberText) {
  AstNode.call(this, line, column);
  this._value = Number(numberText);
};
exports.Number.prototype = Object.create(AstNode.prototype);
 
exports.Variable = function (line, column, variableText) {
  AstNode.call(this, line, column);
  this._name = variableText;
};
exports.Variable.prototype = Object.create(AstNode.prototype);
 
exports.Expression = function (line, column, operand1, operand2, operator) {
  AstNode.call(this, line, column);
  this._left = operand1;
  this._right = operand2;
  this._operator = operator;
};
exports.Expression.prototype = Object.create(AstNode.prototype);
 
exports.Operator = function (line, column, operatorText) {
  AstNode.call(this, line, column);
  this.symbol = operatorText;
};
exports.Operator.prototype = Object.create(AstNode.prototype);

Compilation

Generated JavaScript

Before we generate JavaScript, we need a plan. There are a couple ways we can structure the outputted JavaScript.

One strategy is to translate the RPN expressions to the equivalent human readable JavaScript expression we would create if we had been writing JavaScript all along. For example, if we were to port this RPN example:

a 8 =;
b 2 =;
c a b 1 - / =;

We might write the following JavaScript:

var a = 8;
var b = 3;
var c = a / (b - 1);

However, this means that we are completely adopting the nuances of JavaScript’s arithmetic. In an earlier example, we saw that a helpful runtime error was thrown when any number was divided by zero. Most languages throw an error when this occurs, however JavaScript does not; instead, the result is Infinity. Therefore, we can’t completely embrace JavaScript’s arithmetic system, and we must generate some code to check for divide-by-zero errors ourselves. Adding this code gets a little tricky if we want to maintain the strategy of generating human readable code.

Another option is treating the JavaScript interpreter as a stack machine of sorts and generating code that pushes and pops values to and from a stack. Furthermore, stack machines are a natural fit for evaluating RPN. In fact, it is such a good fit that RPN “was independently reinvented by F. L. Bauer and E. W. Dijkstra in the early 1960s to reduce computer memory access and utilize the stack to evaluate expressions.”

Generating JavaScript code for the same example above, but utilizing the JavaScript interpreter as a stack machine, might look something like this:

push(8);
push('a');
env[pop()] = pop();
push(2);
push('b');
env[pop()] = pop();
push('a');
push('b');
push(1);
temp = pop();
push(pop() - temp);
temp = pop();
if (temp === 0) throw new Error("Divide by zero");
push(pop() / temp);
push('c');
env[pop()] = pop();

This is the strategy we will follow. The generated code is a bit larger, and we will require a preamble to define push, pop, etc, but compilation becomes much easier. Furthermore, the fact that the generated code isn’t as human readable only highlights the benefits of using source maps!

Creating Source Maps

If we weren’t generating source maps along with our generated JavaScript, we could build the generated code via concatenating strings of code:

code += "push(" + operand1.compile() + " "
  + operator.compile() + " "
  + operand2.compile() + ");\n";

However, this doesn’t work when we are creating source maps because we need to maintain line and column information. When we concatenate strings of code, we lose that information.

The source-map library contains SourceNode for exactly this reason. If we add a new method on our base AstNode prototype, we can rewrite our example like this:

var SourceNode = require("source-map").SourceNode;
AstNode.prototype._sn = function (originalFilename, chunk) {
  return new SourceNode(this._line, this._column, originalFilename, chunk);
};
 
...
 
code = this._sn("foo.rpn", [code,
                            "push(",
                            operand1.compile(), " ",
                            operator.compile(), " ",
                            operand2.compile(), ");\n"]);

Once we have completed building the SourceNode structure for the whole input program, we can generate the compiled source and the source map by calling the SourceNode.prototype.toStringWithSourceMap method. This method returns an object with two properties: code, which is a string containing the generated JavaScript source code; and map, which is the source map.

Implementing Compilation

Now that we have a strategy for generating code, and understand how to maintain line and column information so that we can generate source maps easily, we can add the methods to compile our AST nodes to lib/rpn/ast.js.

To play nice with the global JavaScript environment, we will namespace push, pop, etc, under __rpn.

function push(val) {
  return ["__rpn.push(", val, ");\n"];
}
 
AstNode.prototype.compile = function (data) {
  throw new Error("Not Yet Implemented");
};
AstNode.prototype.compileReference = function (data) {
  return this.compile(data);
};
AstNode.prototype._sn = function (originalFilename, chunk) {
  return new SourceNode(this._line, this._column, originalFilename, chunk);
};
 
exports.Number.prototype.compile = function (data) {
  return this._sn(data.originalFilename,
                  push(this._value.toString()));
};
 
exports.Variable.prototype.compileReference = function (data) {
  return this._sn(data.originalFilename,
                  push(["'", this._name, "'"]));
};
exports.Variable.prototype.compile = function (data) {
  return this._sn(data.originalFilename,
                  push(["window.", this._name]));
};
 
exports.Expression.prototype.compile = function (data) {
  var temp = "__rpn.temp";
  var output = this._sn(data.originalFilename, "");
 
  switch (this._operator.symbol) {
  case 'print':
    return output
      .add(this._left.compile(data))
      .add(this._right.compile(data))
      .add([temp, " = __rpn.pop();\n"])
      .add(["if (", temp, " <= 0) throw new Error('argument must be greater than 0');\n"])
      .add(["if (Math.floor(", temp, ") != ", temp,
            ") throw new Error('argument must be an integer');\n"])
      .add([this._operator.compile(data), "(__rpn.pop(), ", temp, ");\n"]);
  case '=':
    return output
      .add(this._right.compile(data))
      .add(this._left.compileReference(data))
      .add(["window[__rpn.pop()] ", this._operator.compile(data), " __rpn.pop();\n"]);
  case '/':
    return output
      .add(this._left.compile(data))
      .add(this._right.compile(data))
      .add([temp, " = __rpn.pop();\n"])
      .add(["if (", temp, " === 0) throw new Error('divide by zero error');\n"])
      .add(push(["__rpn.pop() ", this._operator.compile(data), " ", temp]));
  default:
    return output
      .add(this._left.compile(data))
      .add(this._right.compile(data))
      .add([temp, " = __rpn.pop();\n"])
      .add(push(["__rpn.pop() ", this._operator.compile(data), " ", temp]));
  }
};
 
exports.Operator.prototype.compile = function (data) {
  if (this.symbol === "print") {
    return this._sn(data.originalFilename,
                    "__rpn.print");
  }
  else {
    return this._sn(data.originalFilename,
                    this.symbol);
  }
};

Gluing it Together

From here we have done all the difficult work, and we can run a victory lap by connecting the modules together with a public API, and by creating a command line script to call the compiler.

The public API resides in lib/rpn.js. It also contains the preamble, to initialize __rpn:

var jison = require("jison");
var sourceMap = require("source-map");
var lex = require("./rpn/lex").lex;
var bnf = require("./rpn/bnf").bnf;
 
var parser = new jison.Parser({
  lex: lex,
  bnf: bnf
});
 
parser.yy = require("./rpn/ast");
 
function getPreamble () {
  return new sourceMap.SourceNode(null, null, null, "")
    .add("var __rpn = {};\n")
    .add("__rpn._stack = [];\n")
    .add("__rpn.temp = 0;\n")
 
    .add("__rpn.push = function (val) {\n")
    .add("  __rpn._stack.push(val);\n")
    .add("};\n")
 
    .add("__rpn.pop = function () {\n")
    .add("  if (__rpn._stack.length > 0) {\n")
    .add("    return __rpn._stack.pop();\n")
    .add("  }\n")
    .add("  else {\n")
    .add("    throw new Error('can\\\'t pop from empty stack');\n")
    .add("  }\n")
    .add("};\n")
 
    .add("__rpn.print = function (val, repeat) {\n")
    .add("  while (repeat-- > 0) {\n")
    .add("    var el = document.createElement('div');\n")
    .add("    var txt = document.createTextNode(val);\n")
    .add("    el.appendChild(txt);\n")
    .add("    document.body.appendChild(el);\n")
    .add("  }\n")
    .add("};\n");
}
 
exports.compile = function (input, data) {
  var expressions = parser.parse(input.toString());
  var preamble = getPreamble();
 
  var result = new sourceMap.SourceNode(null, null, null, preamble);
  result.add(expressions.map(function (exp) {
    return exp.compile(data);
  }));
 
  return result;
};

Create the command line script in bin/rpn.js:

#!/usr/bin/env node
var fs = require("fs");
var rpn = require("rpn");
 
process.argv.slice(2).forEach(function (file) {
  var input = fs.readFileSync(file);
  var output = rpn.compile(input, {
    originalFilename: file
  }).toStringWithSourceMap({
    file: file.replace(/\.[\w]+$/, ".js.map")
  });
  var sourceMapFile = file.replace(/\.[\w]+$/, ".js.map");
  fs.writeFileSync(file.replace(/\.[\w]+$/, ".js"),
                   output.code + "\n//# sourceMappingURL=" + sourceMapFile);
  fs.writeFileSync(sourceMapFile, output.map);
});

Note that our script will automatically add the //# sourceMappingURL comment directive so that the browser’s debugger knows where to find the source map.

After you create the script, update your package.json:

...
"bin": {
  "rpn.js": "./bin/rpn.js"
},
...

And link the package again so that the script is installed on your system:

$ npm link .

Seeing Results

Here is an RPN program that we can use to test our compiler. I have saved it in examples/simple-example.rpn:

a 8 =;
b 3 =;
c a b 1 - / =;
c 1 print;

Next, compile the script:

$ cd examples/
$ rpn.js simple-example.rpn

This generates simple-example.js and simple-example.js.map. When we include the JavaScript file in a web page we should see the result of the computation printed on the page:

Great success!

However, we aren’t always so lucky, and our arithmetic might have some errors. Consider the following example, examples/with-error.rpn:

a 9 =;
b 3 =;
c a b / =;
c a b c - / =;
c 1 print;

We can compile this script and include the resulting JavaScript in a web page, but this time we won’t see any output on the page.

By opening the debugger, setting the pause on exceptions option, and reloading, we can see how daunting debugging without source maps can be:

The generated JavaScript is difficult to read, and unfamiliar to anyone who authored the original RPN script. By enabling source maps in the debugger, we can refresh and the exact line where the error ocurred in our original source will be highlighted:

The debugging experience with source maps is orders of magnitude improved, and makes compiling languages to JavaScript a serious possibility.

At the end of the day though, the debugging experience is only as good as the information encoded in the source maps by your compiler. It can be hard to judge the quality of your source maps simply by looking at the set of source location coordinates that they are mapping between, so Tobias Koppers created a tool to let you easily visualize your source maps.

Here is the visualization of one of our source maps:

Good luck writing your own compiler that targets JavaScript!

References

• The source-map library
• The source map specification
• The code used in this tutorial
• Jison
• Reverse Polish Notation at Wikipedia
• Reverse Polish Notation calculator in Bison

This is episode 12, out of a total 12, in the A Node.JS Holiday Season series from Mozilla’s Identity team. It’s the last part, and covers awsbox.

Once you’ve written a server in Node.js, how do you deploy it?
Instead of using a pre-existing “Platform as a Service” (PaaS) provider, the Identity team at Mozilla chose to build custom infrastructure atop Amazon EC2, and we’d like to tell you more about it.

Meet awsbox, a minimalist PaaS layer for Node.js applications that’s currently handling nearly two dozen of the non-critical services that we support.
Awsbox was designed to deliver simple, PaaS-style deployment without sacrificing the flexibility of custom infrastructure.

Using awsbox

In order to deploy a Node.JS project with awsbox, you must make some tiny changes to your application, provide your amazon credentials in the environment, and then you can deploy via the command line.

In terms of app changes, you must:

1. Create an .awsbox.json file that specifies how to start the server.
2. add awsbox as a dependency in your package.json
3. ensure your server binds to the port specified in the PORT environment variable

To provide your amazon credentials, you must set AWS_ID and AWS_SECRET in your environment, two values which you can obtain through the amazon management console.

With the initial application configuration complete, you can npm install which will install awsbox, and you’re ready to create your first server:

$ node_modules/.bin/awsbox create -n MyFirstAWSBOX
reading .awsbox.json
attempting to set up VM "MyFirstAWSBOX"
   ... VM launched, waiting for startup (should take about 20s)
   ... Instance ready, setting human readable name in aws
   ... name set, waiting for ssh access and configuring
   ... public url will be: http://<IP ADDRESS>
   ... nope.  not yet.  retrying.
   ... victory!  server is accessible and configured
   ... applying system updates
   ... and your git remote is all set up
   ... configuring SSL behavior (enable)
 
Yay! You have your very own deployment. Here are the basics:
 
  1. deploy your code:  git push MyFirstAWSBOX HEAD:master
  2. visit your server on the web: http://<IP ADDRESS>
  3. ssh in with sudo: ssh ec2-user@<IP ADDRESS>
  4. ssh as the deployment user: ssh app@<IP ADDRESS>

The final step to deploy your application is to git push:

$ git push MyFirstAWSBOX HEAD:master

And now your Node.JS application is hosted and running on an EC2 instance. At this point, you’ve spent about twenty minutes with awsbox. You’ve made minimal changes to your application. You’ve deployed a new server and gotten your application up and running in EC2. Finally, you’ve got an easy way to push changes that fits within your existing workflow (you just git push to a remote).

Now that you have a feel for how you use awsbox and the basic features it provides, let’s take a step back and look at what it actually is and how it works.

awsbox is … A Minimalistic Contract

Any hosting environment has certain expectations of the application that it will be running, the contract. For awsbox this contract includes the following:

What process(es) should be run are specified by the app in .awsbox.json. At its simplest, the file may look like this:

{
  "processes": [ "path/to/myprocess.js" ]
}

What software must be installed is specified by the app in package.json.

Which port to contact the server is delivered to the app via the PORT environment variable.

In building awsbox, a main goal was minimal invention, to make it easy to “port” an existing application.

awsbox is … A Machine Image

During the process of creating an instance, awsbox creates a machine instance from an “Amazon Machine Image”, which results in a running server that’s ready to accept your node.js application, install its dependencies, and run it. The image is built from the Amazon Linux AMI which is a custom linux distribution provided by amazon, and has access to popular rpm-based package repositories via yum. The ID of awsbox AMI is referenced in the awsbox javascript library.

This image is pre-configured with multiple user accounts. ec2-user is an account that has sudo access to the machine. proxy is an account that hosts an HTTP reverse proxy that with a few steps can serve as an SSL terminator to let you support HTTPS without modifying your application. Finally, the app user is the account that hosts all of your application code, your server logs, the server based git repository that you push to, and the git post-commit hook responsible for installing dependencies and starting your server after you push.

awsbox is … Command Line Tools and Libraries

At the time you npm install awsbox, a collection of javascript libraries and a command line tool are installed locally. The command line tool gives you a much faster way to deploy servers than available through Amazon’s web console, and handles most of the complexity of creating an instance in EC2 that is ssh and web accessible.

The awsbox command line tool also provides many command line verbs to perform basic administration of your awsbox, which can be listed with node_modules/.bin/awsbox -h.

The most interesting verb is create, which actually creates a virtual machine.

awsbox is … A Pile Of Features and Hooks

Finally, any non-trivial server requires more than just a Node.JS service. To support the unknown awsbox allows you to specify yum packages that should be installed at instance creation time. For more custom configuration you have two options:

SSH in and do whatever you need to: The goal of awsbox is to let you move as fast as possible, and sometimes the most expedient way to get a new instance of a service up is to perform required steps manually and write a README. But a more repeatable solution is available…

Write scripts to automatically configure software for you: Awsbox has the notion of hooks, which occur at various stages of instance creation or deployment. Using these hooks, it’s possible to configure mysql, install redis manually, or do whatever you need to in order to get your service running.

Is awsbox for Me?

Having a single consistent mechanism of deploying non-critical services has been an incredible efficiency benefit for our team. Collaboration is easier when you have a simple and well defined contract between application and environment. Diagnosis of issues is faster when you have a consistent set of deployment conventions. Finally, moving from experiment to production environment is less costly when an application has all of its dependencies explicitly expressed.

If you are looking for a deployment solution for your own experimental Node.JS services, give the ideas and design of awsbox a careful look.

Previous articles in the series

This was part twelve in a series with a total of 12 posts about Node.js. The previous ones are:

• Tracking Down Memory Leaks in Node.js
• Fully Loaded Node
• Using secure client-side sessions to build simple and scalable Node.JS applications
• Fantastic front-end performance Part 1 – Concatenate, Compress & Cache
• Building A Node.JS Server That Won’t Melt
• Fantastic front-end performance, part 2: caching dynamic content with etagify
• Taming Configurations with node-convict
• Fantastic front end performance, part 3 – Big performance wins by optimizing fonts
• Localize Your Node.js Service, part 1 of 3
• Localization community, tools & process, part 2 of 3
• Localization in Action, part 3 of 3

Episode XXIII is a barn-storming, hair-raising spectacle of incredible epicness that is sure to delight and amuse. If you want a sneak peak at features under active development, give Nightly a try.

Network Monitor

There’s a new tool in the toolbox: The Network Monitor. It’s a classic waterfall timeline view of network activity on a site. This data’s been available since Firefox 4 via the Web Console, albeit in a less visually pleasing way.

Please file bugs under the Developer Tools: Netmonitor component in Bugzilla.

Remote Style Editor

In Firefox 23, you can now edit styles via a Remote Connection on a suitably-enabled device. This should be great help for App Developers interested in testing and debugging styles on a mobile device over the remote protocol in real time.

As of the time of this writing, the Remote Style Editor should be compatible with Firefox for Android version 23, also scheduled for uplift to Aurora. We are working on incorporating the Style Editor Actors for the remote protocol into the Firefox OS Simulator and investigating what it will take to backport them to Firefox OS release.

Options Panel

We’ve added a Gear menu to the Toolbar containing an Options panel for turning tools on or off. As we add more stuff, this is going to be a popular place to manage preferences related to the Developer Tools.

Currently, there are options to turn on the Light or Dark theme for the tools and enable Chrome Debugging.

Initial SourceMap Support for Debugger Protocol

The first pieces of SourceMap support for the Debugger have landed and we are now able to serve up SourceMapped JS files for your debugging pleasure. Soon to follow will be column support for breakpoints allowing you to debug minified JS with a SourceMap.

Watch for the upcoming blog post by Nick Fitzgerald on Hacks explaining the magic.

Variables View Everywhere

Our Variables View is an improved Object Inspector and an integral part of our Debugger. Naturally, we wanted to put it in Everything. So now the Web Console and Scratchpad have a Variables View. Use the ESC key to close it.

Browser Console

If you have Chrome Debugging turned on, check out the Browser Console. It’s a replacement for the ancient Error Console and gives you a Chrome-context command line for executing JavaScript against the browser. It’s nice and should be enabled by default in Firefox 24.

GCLI Appcache Command

We finally have a little something for developers trying to use App Cache to store offline data. A new appcache command for the Graphical Command Line. You can read about it in Mike Ratcliffe’s The Application Cache is no longer a Douchebag.

Web Console in Debugger Frame

The Web Console is now fully-remoted (and has been since version 18). It now makes use of the Debugger’s current Frame if paused on a breakpoint.

Multiple Paused Debuggers

You can now debug multiple tabs at the same time using the Script Debugger. Previously, when attempting to use the debugger on two separate tabs, you’d be given a notification to resume the debugger in the other tab. Now you can debug as many tabs as you like.

There is one caveat to this awesome power, however. Due to the nested event loops each Debugger creates, you have to resume each tab in the order in which they were paused. Debug carefully and always carry a big stack.

You can see a comprehensive list of bugfixes in table form in Firefox 23 Developer Tools Fixes.

Using Redis on the server-side

When adding records in Redis, we aren’t working with a relational database like in MySQL or PostgreSQL. We are working with a structure like IndexedDB where there are keys and values. So what do we need when we only have keys and values to work with for a notes app? We need unique ids to reference each note and a hash of the note metadata. The metadata in this example, consists of the new unique id, a creation timestamp and the text.

Below is a way of creating an id with Redis in Node and then saving the note’s metadata.

// Let's create a unique id for the new note.
client.incr('notes:counter', function (err, id) {
 
...
 
    // All note ids are referenced by the user's email and id.
    var keyName = 'notes:' + req.session.email + ':' + id;
    var timestamp = req.body.timestamp || Math.round(Date.now() / 1000);
 
    // Add the new id to the user's list of note ids.
    client.lpush('notes:' + req.session.email, keyName);
 
    // Add the new note to a hash.
    client.hmset(keyName, {
      id: id,
      timestamp: timestamp,
      text: finalText
    });
 
...
 
});

This gives us the following key pattern for all notes on the server-side:

1. notes:counter contains all unique ids starting at 1.
2. notes:<email> contains all the note ids that are owned by the user. This is a list that we reference when we want to loop through all the user’s notes to retrieve the metadata.
3. notes:<email>:<note id> contains the note metadata. The user’s email address is used as a way to reference this note to the correct owner. When a user deletes a note, we want to verify that it matches the same email that they are logged in with, so you don’t have someone deleting a note that they don’t own.

Adding IndexedDB on the client-side

Working with IndexedDB requires more code than localStorage. But because it is asynchronous, it makes it a better option for this app. The main reason for why it is a better option is two-fold:

1. You don’t want to wait around for all your notes to process before the page renders all elements. Imagine having thousands of notes and having to wait for all of them to loop through before anything on the page appears.
2. You can’t save note objects as objects – you have to convert them to strings first, which means you will have to convert them back to objects before they are rendered. So something like { id: 1, text: 'my note text', timestamp: 1367847727 } would have to be stringified in localStorage and then parsed back after the fact. Now imagine doing this for a lot of notes.

Both do not equate to an ideal experience for the user – but what if we want to have the ease of localStorage’s API with the asynchronous features of IndexedDB? We can use Gaia’s async_storage.js file to help merge the two worlds.

If we’re offline, we need to do two things similar to the server-side:

1. Save a unique id for the note and apply it in an array of ids. Since we can’t reference a server-side id created by Redis, we’ll use a timestamp.
2. Save a local version of the note metadata.

var data = {
  content: rendered,
  timestamp: id,
  text: content
};
 
asyncStorage.setItem(LOCAL_IDS, this.localIds, function () {
  asyncStorage.setItem(LOCAL_NOTE + id, data, function () {
    ...
  });
});

The structure of the IndexedDB keys are very similar to the Redis ones. The pattern is as follows:

1. All local ids are saved in a localNoteIds array
2. All local note objects are saved in note:local:<id>
3. All remote/synced ids are saved in a noteIds array
4. All remote/synced note objects are saved in note:<id>
5. Local notes use a timestamp for their unique id and this is converted to a valid server id once Redis saves the data

Once we’re online, we can upload the local notes, save the remote ones on the client-side and then delete the local ones.

Triggering note.js on the client-side

Whenever we refresh the page, we need to attempt a sync with the server. If we are offline, let’s flag that and only grab what we have locally.

/**
 * Get all local and remote notes.
 * If online, sync local and server notes; otherwise load whatever
 * IndexedDB has.
 */
asyncStorage.getItem('noteIds', function (rNoteIds) {
  note.remoteIds = rNoteIds || [];
 
  asyncStorage.getItem('localNoteIds', function (noteIds) {
    note.localIds = noteIds || [];
 
    $.get('/notes', function (data) {
      note.syncLocal();
      note.syncServer(data);
 
    }).fail(function (data) {
      note.offline = true;
      note.load('localNoteIds', 'note:local:');
      note.load('noteIds', 'note:');
    });
  });
});

Almost done!

The code above provides the basics for a CRD notes app with support for local and remote syncing. But we’re not done yet.

On Safari, IndexedDB is not supported as they still use WebSQL. This means none of our IndexedDB code will work. To make this cross-browser compatible, we need to include a polyfill for browsers that only support WebSQL. Include this before the rest of the code and IndexedDB support should work.

The Final Product

You can try out the app at http://notes.generalgoods.net

The Source Code

To view the code for this app feel free to browse the repository on Github.

Setting Up the Geeksphone Device

To push apps to the Geeksphone Firefox OS Developer Preview phone, you first need to enable Remote debugging. This can be done from the Settings app by selecting Device information > More Information > Developer -> Remote debugging. Now we are ready to configure the computer running the Simulator.

Windows

The team at Geeksphone recently released a set of drivers for Windows to support USB communication with their phones. The drivers are available at Geeksphone’s Web Site (direct ZIP link).

To install them, first download and extract the zip file to a known location on your system. Next, connect the phone to your machine using the provided USB cable. Click on the Start Button and enter “Device Manager” in the Search programs and files text entry field and press enter. This will launch the Windows Device Manager. Alternatively, you can launch the Device Manager from the icon located in the Windows Control Panel.

The connected phone will be listed under the Other Devices category. Right click on the Android label and select Update Driver Software….

In the Update Driver Software dialog, choose Browse my computer for driver software.

Locate the usb_driver folder from the Geeksphone download and make sure the Include subfolders checkbox is checked. Click on the Next button.

You will most likely receive a Windows Security alert. Select the Install this driver software anyway entry.

This will install the proper USB drivers and list the phone as Geeksphone Device in the Device Manager.

Launch the Firefox OS Simulator. The Dashboard should now contain a Push button and a Device connected message, and you should be able to add your Firefox OS app to the Simulator and push it to the phone.

Linux

If you are running the Simulator on a Linux machine, you will need to create or modify a udev rules file for the device. This process is described in “Setting up a Device for Development” (Steps 3.a and 3.b). The Geeksphone Firefox OS Developer Preview phone idVendor attribute is “05c6”, so your android.rules file should contain an entry similar to:

SUBSYSTEM==”usb”, ATTR{idVendor}==”05c6”, MODE=”0666”, GROUP=”plugdev”

After making the above changes, either reboot the system or restart the udev service:

sudo service udev restart

If you make these changes and the push to device button does not show up in the Simulator Dashboard, please see this workaround.

Mac

If you are running the Simulator on a Mac, no additional configuration is required to enable push to device.

Reference

Additional information about setting up and using the Firefox OS Simulator, including installing, adding apps, debugging and using the push to device capability can be found on the MDN page for the Firefox OS Simulator.

For other native technology stacks, extensible components are all but assumed – not so much for the web. Soon, that all changes. We are on the verge of a declarative renaissance that will dramatically advance app development for the web platform, and Web Components will drive it.

X-Tag and Web Components offer features that obliterate the status quo for layout, UI, and widget development – here’s a few notable Web Component features:

• Create real custom elements the browser understands
• Stop the instantiation madness: $$(‘button.super’).initSuperButton()
• Remove unmanageable HTML widget guts from your app’s view files
• Work with sharable components, based on standard technologies

Meet the Web Components Family

Web Components is a group of W3C specifications, quickly moving toward standardization, that provide a robust HTML component model. You should not assume the following specs are implemented in your browser of choice. While these specifications are in various stages of implementation across browsers, you can use X-Tag (with either Mozilla or Google’s prollyfill) today to create custom elements that work well in recent version of Firefox, Chrome, Safari, and stock mobile browsers. X-Tag is a powerful sugar library primarily focused on wrapping and enhancing one of the draft-state Web Component specs: Custom Elements (document.register). We’ll get to X-Tag shortly – but for now, let’s quickly review the key features of each spec:

Custom Elements

Custom Elements provides you a way to create new elements for use in your environment. There are two ways to declare a new custom element, the imperative DOM API – document.register(), and the declarative HTML tag – (whose DOM constructor is HTMLElementElement). After declaration, new custom elements can be created in the same ways native elements are, such as document.createElement, presences in original source (the markup of a page), and innerHTML, etc.

Here’s an example of what a custom element registration looks like in both the declarative and imperative styles:

document.register('x-foo', {
  prototype: Object.create(HTMLElement.prototype, {
    readyCallback: { 
      value: function(){
        // do stuff here when your element is created
        this.innerHTML = '<div>Barrrr me matey!</div>';
      }        
    },
    bar: {
      get: function() { return 'bar'; },
    },
    // add more properties to your custom prototype
    // ...
  })
});

<element name="x-foo">
  <script>
    if (this !== window) {
      this.register({
        prototype: {
          readyCallback: { 
            value: function(){
              // do stuff here when your element is created
              this.innerHTML = '<div>Barrrr me matey!</div>';
            }        
          },
          bar: {
            get: function() { return 'bar'; },
          }
        }
      });
    }
  </script>
</element>

Shadow DOM

The Shadow DOM allows you to encapsulate structural and supporting elements within components. Elements within nodes remain visible for purposes of display UI (depending on the type of element and your styles), but are hidden from the rest of your application code, unless you explicitly cross the shadow boundary.

HTML Templates

HTML Templates bring simple DOM templating and markup reuse to the web platform – which are often shimmed today using the HTMLScriptElement + DocumentFragment hack-pattern.

HTML Imports

HTML Imports are external HTML documents that contain declarative component definitions. HTML component documents can by imported using the link element with the rel attribute value import. Imported resources may themselves contain additional sub-imports, which the browser then retrieves and performs automatic dependency resolution upon.

Web Components + X-Tag = WINNING

Mozilla’s X-Tag library enhances the imperative (JavaScript) route for creating custom elements. X-Tag’s primary interface is the xtag.register() method – it wraps the soon-to-be standard document.register() DOM API with features and functionality that make development of amazing custom elements effortless.

Creating a Custom Element

Here’s a quick example of what registering a custom element looks like using X-Tag:

xtag.register('x-pirate', {
  lifecycle: {
    ready: function(){
      this.innerHTML = '<blockquote>' +
                         '<img src="pirate-1.png"/>Barrr me matey!' +
                       '</blockquote>';
    }
  },
  accessors: {
    src: {
      // X-Tag's attribute sugar relays any value passed to the src 
      // setter on to the src attribute of our <x-pirate> and its
      // <img> element (specified by CSS selector), and vice versa.
      attribute: { selector: 'img' },
      set: function(){
        // When a <x-pirate>'s src attribute/setter is changed, we 
        // stop everything to announce the arrival of a new pirate.
        // Ex: doc.querySelector('x-pirate').src = 'pirate-2.png';
        alert("There's a new captain on deck ye scurvy dogs!");
      }
    }
  },
  events: {
    // This is an example of X-Tag's event and pseudo systems. The
    // "tap" custom event handles the dance between click and touch,
    // the ":delegate(img)" pseudo ensures our function is only 
    // called when tapping the <img> inside our <x-pirate>.
    'tap:delegate(blockquote > img)': function(){
      alert("A pirate's life for me!");
    }
  }
});

To the Democave Batman!

We’re actively working on a custom element UI toolkit and style pack that will make development of app interfaces a breeze. It’s still in very early stages, but we have a few demos for you.

Get the Code

Head over to X-Tags.org and grab the code to develop custom elements of your own. After you get the hang of things, start contributing to our open source effort!

We’ve started reviewing your proposals, and in the next few weeks we plan to notify application builders and porters who’ve been selected. We regret we can’t respond to the thousands of you with great ideas for apps for Firefox OS. There will be other opportunities to get access to the the Developer Preview device. Please keep working on your apps. We can’t wait to see them in Firefox Marketplace.

Hello HTML5 app developers, the open mobile web is calling.

We know you’re out there, chomping at the bit, coding, testing, reading documentation, downloading and running the Firefox Simulator. And you’re ready to ‘Send to Device.’ You just need to get your hands on a device.

Today we’re announcing a new program with you in mind. We call it: Phones for Apps for Firefox OS.

Firefox Marketplace on the Geeksphone Keon

Maybe you’ve built apps in the past for Chrome, webOS, Blackberry WebWorks, or the PhoneGap store. Maybe you’ve created beautiful web apps for a desktop environment and now you want to port them to mobile. Maybe you’re a student about to start a summer break. We know you may not live anywhere near Bogota, Colombia or Warsaw, Poland, locations of upcoming App Workshops.

Wherever you are

Wherever you are, if you can show you’ve got a great app idea and the skill to build it, we’d love to see your apps in the Marketplace when the Firefox OS launch begins later this summer. And to sweeten the deal, we’ll send a Firefox OS Developer Preview device for you to work with now.

When Firefox OS phones become available to consumers in select locales this summer, you’ll have an opportunity that only comes around once—a first-mover advantage in Firefox Marketplace. End users in Latin America, Eastern Europe and other launch locations will be on the lookout for playful and practical apps to install: games, tools, and utilities as well as locally relevant news, sports, travel, entertainment, review apps, and social sharing experiences. And you can build and submit them now!

Apply now

Tell us about the Firefox App you’d like to build or port. If your proposal is accepted, we’ll send you a Geeksphone Keon. Our device inventory is limited and our launch dates are approaching fast, so act now. This program will close at the end of May or when our limited supply of Geeksphones runs out. There’s a limit of one phone per app proposal. We can’t wait to see what you’re working on. There’s never been a better time to get started.

Apply here.

Most of you remember the Hello Chrome, it’s Firefox calling! blog post right here in Mozilla Hacks demonstrating WebRTC video chat between Firefox and Chrome. It raised a lot of attention. Since then we here at Fresh Tilled Soil have seen a tremendous amount of startups and companies which have sprung up building products based WebRTC video chat technology. Tsashi Levent-Levi who is a WebRTC evangelist has been interviewing most of these companies on his blog, the list is quite impressive!

WebRTC chat demo

Much like most of early adopters we have been playing around with WebRTC for quite awhile now. We have of course created our own WebRTC video chat demo and have also very recently released WebRTC video chat widgets.

The widgets work very simply, anybody can take the following HTML embed code:

<!-- Begin Fresh Tilled Soil Video Chat Embed Code -->
<div id="freshtilledsoil_embed_widget" class="video-chat-widget"></div>
<script id="fts" src="http://freshtilledsoil.com/embed/webrtc-v5.js?r=FTS0316-CZ6NqG97"></script>
<!-- End Fresh Tilled Soil Video Chat Embed Code -->

and add this code to any website or blog post. You’ll see the following widget on their website:

From here it’s dead simple to start a WebRTC video chat, just make up a name for a room, type it in and click start chat. Tell the other person to do the same and you’re all set.

As always make sure you’re giving this a try in Firefox Nightly or the latest stable build of Google Chrome. If you are on a tablet make sure you are on Google Chrome beta if you are using the Google Chrome browser.

Something else to note is that for this first version our video chat is limited to just two participants per a room. If a room name is occupied by two people the third person who tries to connect to this room simply won’t be able to connect.

How It Works

Without getting too deep into the code behind how WebRTC video chat actually works, let’s briefly go over what is actually happening behind the scenes when you click the start chat button and how WebRTC video chat actually works. Here is a step by step timeline of what actually happens to give you a better idea:

A quick note about this step: “Once remote media starts streaming stop adding ICE candidates” – this is a temporary solution which might result in suboptimal media routing for many network topologies. It should only be used until Chrome’s ICE support is fixed.

A quick and very important tip to remember when you are trying to get this to work. We used a ‘polyfill’ like technique as shown in this article by Remy Sharp. As Remy describes we wrote a piece of code to adapt for the Firefox syntax to get cross-browser functionality.

Issues We Ran Into and How We Solved Them

As you might expect we ran into a number of problems and issues trying to build this. WebRTC is evolving quickly so we are working through a number of issues every day. Below are just some of the problems we ran into and how we solved them.

PeerConnection capability in Google Chrome

While working with the new PeerConnection capability in Chrome we discovered a strict order of operation for it to work; more specifically:

• Peers must be present with local streaming video before sending SIP (offer/answer SDP)
• For ‘Answerer’; Do not add ICE candidate until the peer generates the ‘Answer SDP’
• Once remote media starts streaming stop adding ICE candidates
• Never create peer connect for answerer until you get the ‘Offer SDP’

We fixed it by handling those issues and handling the connection in the order described above. This was crucial to making the connection work flawlessly. Before we did that it would work only every once in a while.

Added latency due to lag

When streaming to a mobile device there is added latency due to lag and limitations of surfing the net via mobile phone.

We solved this by making the resolution of streamed video reduced via a hash tag at the end of the URL. URL can optionally contain '#res=low' for low resolution stream video & '#res=hd' for HiDefinition streaming video as an optional URL parameter. A quick note here that other configurable properties are now available such as frames per second which you can use for this same purpose.

Recording the WebRTC demo

We’ve been dabbling with recording video WebRTC demo. When recording video we used the new JavaScript type arrays to save the streaming data. We quickly discovered that it is only possible to record the video and audio separately.

We solved this by creating two instances of recording, one for the audio and one for the video, that utilized the new javascript data types and recorded both streams simultaneously.

Conclusion

It’s exciting to dabble in this stuff, we love WebRTC so much that we created an entire page dedicated to our experiments with this technology and others which we believe will transform the web in 2013. If you have any question please give us a shout.

As the editor of several programming newsletters, I frequently get two types of e-mails from developers. Those reaching out to ask if I can mention their projects, and those expressing surprise and excitement that their work has been featured. If you’re a developer doing good work but feel more like you’d be in that second group, the three steps in this article are for you.

Before we get started, there’s a stumbling block we need to kick away. Terms like ‘marketing’ and ‘advertising’ are dirty words for many developers and it’s not uncommon for developers to be reluctant to do much promotion. ‘Build it and they will come’ used to work when exciting open source projects were few and far between but now everyone seems to be working on something and making a noise about it. Few of the successes you see come through pure luck but because developers are actively promoting their work or, at least, making it discoverable. It’s time to join them!

Step 1: Get your project ready

Before you can promote your project, you need to make it attractive to potential users and evangelists (including general wellwishers, the media, and other developers).

A good name

Ensure your project has a palatable name. It doesn’t need to be clever or even descriptive, but it’s worth avoiding innuendos that may present a problem down the line. For example, the popular Testacular and Authgasm projects, are now named Karma and Authlogic respectively after users raised a fuss.

You should perform a search for the name you choose to be sure you’re not clashing with anything else that’s popular or trademarked (did you know Firefox was called Phoenix and Firebird prior to Firefox?). The US Patent and Trademark Office has an online trademark search facility.

A benefit of having a relatively unique or uncommon name is so you can search for it over time (or even set up a Google Alerts notification for the name) and find mentions of your project without many irrelevant results popping up. If you want to have something descriptive but unique, consider joining two words together. For example, when I created a Ruby library to do natural language detection, I called it WhatLanguage and it’s easy to search for.

An official homepage or project URL

The term ‘homepage’ is a bit outdated but you ideally need a single ‘home’ URL that you can promote and point people to in relation to your project. You don’t need to splash out on a fancy template or even a domain name, but your project needs a focal point. That could be an entire site with its own domain, such as those for Yeoman or HTML5 Boilerplate, a simple single page on an existing domain, such as that for RoughDraft.js, or even a regular GitHub repo, such as for vague.js.

If you have the freedom to do so, make sure your site looks good on the major browsers (including mobile), hook up some analytics to your page and ensure the <title> tag is well written. Use a title like “MyProject – A JavaScript Library to X, Y and Z” instead of just “MyProject – About” or a blank title. With social bookmarking, this matters as you can’t guarantee your evangelists will write a good title of their own.

If you’re not a Web designer, don’t have the time to spend making a complete design, but still want a complete site rather than just a GitHub repo and README, consider using a framework like Bootstrap as it’ll provide a clean layout out of the box and you can forget about many cross browser and device issues.

Documentation and copywriting

It’s only just a cliché that developers don’t like to write documentation, but you need something for potential users to fall back on, and time invested in producing useful documentation up front will pay dividends later.

At a cynically bare minimum, you need to write enough documentation that someone will be confident about sharing your link or promoting your project and not feel like they’re sending their own followers into a black hole of misunderstanding. This means your homepage or README needs to cover a few angles. You’ll need to:

• Prominently feature a “[noun] is” paragraph. An alarming number of project homepages don’t explain, in simple terms, what the project is actually for or does. If you’ve built a JavaScript library that does language detection, say, you have to say so. For example: “LanguageDetect is a JavaScript library for detecting the natural language of text.”

  An excellent example of this in action is on libcinder.org where it states right up front: “Cinder is a community-developed, free and open source library for professional-quality creative coding in C++.” Perfect!

• Write clear titles, subheadings, and support copy. At a bare minimum, ensure titles, subtitles, and any sort of writing on your homepage are straightforward and clear. Write for the lowest common denominator on your homepage. You can get more advanced elsewhere.

• Write a beginner’s tutorial and link to it from your home page. Unless everything’s simple enough to explain on a single page, quickly write a tutorial that covers basic installation and usage and either include it in your README file or put it on the Web and link to it from your README and/or homepage.

• State dependencies and requirements clearly. Does your library only work on a specific version of Node? Is it a browser extension for Firefox? Does your code require PostgreSQL, Redis, or another specific database? Be sure to include a bulletpoint list of dependencies and requirements for your project to be usable so as not to disappoint potential users.

• Specify the license for your code. While you could get away with keeping your licensing information tucked away in a LICENSE file in your GitHub repo, specifying what license your code is released under up front and center will help put many developers at ease. Likewise, if your project is commercial is nature and costs money, don’t hide that detail away and mislead visitors.

• If your project is a library or API, feature some example code on the homepage. Unless your library is particularly complex, let visitors see an example of its usage on the project homepage. If your API is good, this could be a great way to get an ‘easy sale.’ I’m not a huge fan of the code example chosen but the homepage for Ruby shows off this technique.

Extra materials

A blog post is a great way to introduce a project that might need more background or have more of a story than it’s practical to tell on a homepage or within documentation. If there’s any sort of story behind your project, a blog post is a great way to tell it. Be sure to link to the post from your project’s homepage and consider promoting the blog post separately to relevant sites within your niche.

If you have the ability, recording a screencast or other sort of video can help. Could you put together a simple 5 minute screencast of how to install and use your library? Or have you built a game that could be demonstrated in a few minutes of gameplay? Record a simple video, put it on YouTube, and embed it on your homepage. Your accent doesn’t have to be as crisp as a newsreader’s and you don’t even have to appear within the video. All that matters is you get to the point quickly and your audio is tolerable (not muffled, clipping, or drowned in background music).

As the editor of several programming newsletters, I look at thousands of projects each year, and it’s still uncommon to see simple screencasts, yet they certainly help a project stand out and, as a consequence, make it more likely for me to talk about it. You can see a perfect example on Punch’s homepage. The early popularity of Ruby on Rails also depended upon a popular ‘build a blog engine in 15 minutes’ video, back when the concept of using video to promote an open source project was very novel.

If you’re sticking to the straight up, GitHub README approach (and it’s certainly not a bad idea for a simple library), a bonus tip is to create a tiny screencast of your code in action and convert it to an animated GIF for inclusion in your README. Richard Schneeman outlines this technique in Use GIFs in your Pull Request for Good, not Evil. The result is striking and could help your README stand out.

For further ideas on how to make your project stand out before you begin promoting it, check out the great How to Make Your Open Source Project Really Awesome by Michael Klishin. It digs into more detail about versioning, announcements, having a changelog and writing good documentation.

Step 2: Get the word out

You’ve polished your project, got a URL to promote, and you’re ready to get the news out.

A word of caution, however. Don’t use every technique on day one. You could overload your site with traffic or, worse, be subjected to a barrage of online criticism if your work or site is broken. With something like a library or tool, a gentler approach will work well and building up small streams of visitors and users over time will give you a much better time.

Social networking

Your own social networking profiles are always a good place to start if you have them. You’ll get more immediate feedback from people who actually know you and if your project is particularly interesting, it could go viral even from a single mention.

A great example of a simple project going viral was YouTube Instant by Feross Aboukhadijeh. Feross built YouTube Instant quickly, mentioned it on Facebook before going to bed, and woke up to a flood of traffic and press mentions.

If you like to experiment and have several bucks going spare, you could also consider paying for a promoted post on Facebook. This will give your post more visibility in your news feed, but is best reserved for if your Facebook friends are mostly developers or people likely to be interested in your project. If not, and you’d still like to spend some money, consider an ad on Reddit or a relevant programming blog instead.

Influencers, bloggers, and niche media

Whether you’re working on a JavaScript library, Firefox extension, backend app in Rails, or a theme for Bootstrap, your code will fit into one or more niches and every technical niche has a variety of ‘influencers’, people and publications who are popular and well known for the topic at hand.

Getting a tweet, retweet, or even an entire blog post from an influencer could have a significant impact on your project, as could being invited to blog elsewhere (Mozilla Hacks, for example!). If Brendan Eich tweeted about your JavaScript library, Lea Verou wrote a blog post about a CSS trick you discovered, or Paul Irish mentioned a Web development tool you built in a talk, you would attract a lot of interest quickly. It is key, however, to realize there are many great influencers in every space and you’ll achieve nothing by hounding any one person so be prepared to move on.

Spend some time working out who the influencers and key publications are in your niche. For Twitter, Followerwonk is a handy tool that searches Twitter biographies for certain words. If you search for “javascript” the first page includes several users who would be useful to reach out to if you had a particularly interesting JavaScript-related release to promote. Reaching out on Twitter can be as simple as a single tweet and many busy folks prefer Twitter as it takes less time to reply than an e-mail. A single tweet from @smashingmag could drive thousands of visitors your way, so consider tweeting them, and other similar accounts, when you have something relevant.

I’d also advise looking for blogs and e-mail newsletters in your niche. Start with something as simple as Googling for “javascript blog”, “javascript newsletter”, “css blog” or whatever’s relevant to your project. Most bloggers or e-mail newsletter publishers will not be offended by you sending them a quick note (emphasis on quick) letting them know about your work. Indeed, some weeks there can be a shortage of interesting things to write about and you might be doing them a huge favor.

If you choose to e-mail people (and your project will probably be more substantial than a few hours’ work to justify this), take care not to make demands or to even expect a reply. Many bloggers and influential people have overflowing inboxes and struggle to reply to everything they receive. Make your e-mail as easy to process as possible by including a single URL (to your now superb homepage or README) and include your “[noun] is” paragraph. Don’t take a non-response as an insult but keep moving on to the next most relevant person. You might even consider taking a “Here’s my project that does X, Y and Z. No reply needed, I just thought you might like it” approach. Softly, softly works here, as long as you get to the point quickly.

How to get attention from internet celebrities by Jason Cohen and How to Write the Perfect Outreach Email by Gregory Ciotti go into more detail about e-mail etiquette when promoting your work to influencers. While you might not need to contact any ‘celebrities’ in your niche, the principles of keeping it short, including a call to action, and ensuring your work is appropriate to the person are really true for anyone you’re sending unsolicited messages to.

Podcasters are an often forgotten source of promotion opportunities too. While some podcasts don’t cover news or new releases at all, many do, and being on the radar of their hosts could help you get a mention on a show. Smashing Magazine has put together a list of tech podcasts covering the areas of design, user experience, and Web development in general. Again, keep your e-mails short and sweet with no sense of expectation to get the best results.

User curated social news sites

As well as reaching influencers and niche media, sometimes reaching the public ‘firehose’ of news can work too, and there are few better examples of these in the modern world of development than Hacker News or Reddit.

Hacker News in particular is notoriously hard to reach the front page on and ‘gaming’ it by getting other people to vote up your post can backfire. (Indeed, it will backfire if you link people to your post on Hacker News and encourage them to upvote. They have ways of detecting this behavior. Get people to manually find your post instead.) If you do reach the front page of Hacker News, of course, you can certainly expect an audience of many thousands of developers to be exposed to your work, so be sure to try.

With Reddit, the key isn’t to dive straight into a huge sub-Reddit like /r/programming but to look for sub-Reddits more directly related to your project. For a JavaScript library, I’d post to /r/javascript or possibly /r/webdev. Reddit ads can also perform well if you’re OK with spending some money and these can be targeted to specific sub-Reddits too.

There are many similar sites that are less well known but which are respected in their niches and can drive a lot of interested visitors, including Designer News (mobile and Web design), DZone (general developer stuff), EchoJS (JavaScript), RubyFlow (Ruby and Rails), and Lobste.rs (general hacker and developer stuff). Finding the right site like this and taking time to make an on-topic, well written post will help a lot.

The mass media / press

This article is primarily focused on the promotion of open source and front-end projects and these are typically not frequently covered in print or on the TV or radio. If, however, you think the mass media would be relevant for your project, here are some other articles packed with handy tips:

• How to PR Like a Pro: A Guide to Getting Media Attention
• How To Get Media Coverage For Your Startup: A Complete Guide
• Getting Press for Your Website, Application, or Service
• How to Get Major Media Coverage For Your Business with No Connections
• How to Contact Press (And Increase Changes To Get Press Coverage) (oriented around promoting indie games but the essentials are there)

Step 3: Maintain momentum

You’ve built up some interest, your GitHub stars, Reddit votes, and pageviews are all rocketing up, but now you want to capitalize on the attention and maintain some momentum.

User support

Whether you’ve built an open source project or a cool tool, you’re going to end up with users or fellow developers who want to provide feedback, get help, or point out issues with your work. On GitHub, the common way to do this is through the built-in ‘issues’ tracker, but you might also find people start to e-mail you too.

Be sure to define a policy, whatever it is. Users won’t feel good about opening issues on your GitHub repo if there are already many unresolved issues there and your project could stagnate. Ensure you respond to your audience or at least make your policy clear within your README or on your site. If you don’t want issues raised or code contributions, make this clear up front.

Extending your reach

For many projects, create a dedicated Twitter account, blog, Facebook page, or Google+ page in advance is overkill, but if your project starts to take off, consider these things. They’ll provide an extra way not only for users to remain in touch with your project but also a way for them to help promote it by retweeting things you post or by directing potential new users your way.

You can also extend your reach in person by going to user groups and conferences and, if you’re really lucky, you can speak about your work too. This is a great way to get new users as people are much more likely to look into your work if they’ve met you in person.

Avoid being defensive

If your project does well on sites like Hacker News or Reddit, you’ll be tempted to read all of the comments your peers leave, but be careful. Comments about your work will, naturally, seem magnified in their intensity and critical comments that might not actually be mean spirited may seem as if they are to you.

It’s hard, but the best policy is to not let any overtly mean comments get to you, duly correct any observations that are wrong, and to thank anyone who goes out of their way to compliment your work. Even if you’re in the right, with the lack of body language and verbal cues, being too defensive can look bad online and result in the post becoming a lightning rod for drama. Engage as best you can, but if it feels wrong to reply to something, listen to your gut.

Be careful if you go into a new community to promote your work and get negative feedback. Most communities have rules or expectations and merely entering a community to promote your work is frequently considered a faux pas. Be sensitive to people’s environments and try to abide by a community’s rules at all times.

The long term

If your project does particularly well, you could be presented with the opportunity of turning it into a business in its own right. Many simple open source projects, often started by a single developer, have turned into long term work or even entire companies for their creators.

Back in 2010, Mitchell Hashimoto released Vagrant, a Ruby-based tool for building a deploying VirtualBox-based virtualized development environments. In late 2012, Mitchell launched Hashicorp, a company providing Vagrant consulting services to enterprise customers. An even higher profile example is Puppet Labs, a company built around the Puppet open-source configuration management tool and which has taken total funding of $45.5 million so far.

If your project becomes respected and heavily used within its field, you might also be approached to write a book or article about it or even speak at a conference. This is a good sign that your project has ‘made it’ to some extent as publishers and event organizers are in the business of working out what it makes business sense to present.

Putting it all together: A checklist

This has only been a basic introduction to promoting your work and with practice you’ll come up with tons of tips of your own (it’d be excellent if you could share some in the comments here). Based on all of the ideas above, here’s a basic checklist to run through next time you release a new project and want to get some added exposure:

• Focus most of your efforts on your project’s homepage or README.
• Check your project’s name doesn’t clash with anything else and is unique enough to find references to your work later.
• Promote your work to your closest social group first to unbury any problems with your work.
• Record a screencast or write a blog post about your project if some extra background would be useful for others.
• Work out a perfect *”[project name] is”* sentence to describe what your project is or does.
• Use your *”[project name] is”* sentence to give your page a descriptive title.
• Find influential people, blogs, podcasts, and e-mail newsletters in your niche and send them a short, pleasant note.
• Post to social news and bookmarking sites. Ensure your title is descriptive.
• Use your *”[project name] is”* sentence in e-mails and contacts with influencers.
• Take a positive, “look on the good side” approach to responding to comments about your work.

Good luck!

New features

In our preview coverage, we listed the new features for this version:

• Push to Device
• Rotation simulation
• Basic geolocation API simulation
• Manifest validation
• Stability fixes for installation and updates to apps
• Newer versions of the Firefox rendering engine and Gaia (the UI for Firefox OS)

Since then, apart from verifying and making the above functionality stable, other notable improvements are:

• Keyboard shortcut to repackage/reinstall/restart the current app – drastically improving workflow speed, especially for packaged apps
• Significantly reduced download/installation size of the Firefox OS Simulator
• Faster start time (partly due to above with smaller size)
• Much newer versions of Firefox OS and Gaia
• General bug fixes, making it more functional and reliable
• OS-standard ways in the menu to close the Simulator, with corresponding keyboard shortcuts (Alt + F4 on Windows, Cmd + Q on Mac, Ctrl + Q on Linux)

Firefox OS Simulator documentation

As part of this release, we’d also like to highlight our updated Firefox OS Simulator documentation on MDN and also our Firefox OS Simulator walkthrough example.

Download/install the Firefox OS Simulator

You can download version 3.0 of the Firefox OS Simulator from our add-ons web site.

Please let us know what you think in the comments! If you encounter any bugs or problems, please file a bug.

Not a contestant? There are other reasons to be excited. Most importantly, all of these demos are completely open-source, making them wonderful lessons in the exciting mobile experiences you can create today using only the skills you already have.

The Results

Winners

• First place: Memory Cube by sophomore Jesus Perez
• Second place: Writerrific by designer and developer Laurens Debackere
• Third place: Loc Tag by newcomer bzub

Runners-up

• Paint my dash by mobile Web lover Giovanny Andrés Góngora Granada
• Ubercalc by the always impressive JoanC

The March Derby saw some great entries, from games to productivity applications to wonderfully useful location-based services and more. Please join me in congratulating these winners and all of our contributors for making the wireless world a better and more exciting place.

Want to get a head start on an upcoming Derby? We are now accepting demos related to getUserMedia (May) and WebGL (June). Head over to the Dev Derby to get started.