Developing in Firefox OS: How about a tool to scaffold apps?

Webs Externas

Tags:

By The Product Development and Innovation (PDI) team at Telefonica Digital

A Firefox OS app generator for Yeoman

30 September 2013: After developing for Firefox OS at work for a while, we’ve decided to make Firefox OS app development a bit easier. We came up with the idea of a generator for Yeoman, a tool to scaffold apps.

This generator will scaffold a directory structure very similar to the one we’ve used in our own projects. There you will find Grunt (an automation tool) tasks to setup pipelines to compile your Sass stylesheets, run your Mocha tests, build a zip file with your app, deploy the app to a Firefox OS device, etc.

Let’s get started

Requirements:

Node (>= 0.10)
Sass ($ gem install sass)
Grunt (read this to install Grunt)

First you need to install Yeoman globally, if you still don’t have it in your system. Then you can install the generator (globally as well).

[php]$ npm install -g yo
$ npm install -g generator-firefoxos</pre>
[/php]

After that, you’re ready to create your app! Make a directory, and run yeoman from it:

[php]$ mkdir myapp
$ cd myapp
$ yo firefoxos</pre>
[/php]

You will be asked several questions, like the name of your app (it can include blank spaces, uppercase letters, etc.), your Github user name, and whether to add Gaia’s Building Blocks and Backbone. For the sake of learning, please answer YES to these questions this time.

Don’t panic if you see half of the Internet being downloaded! Most of it are development tools that won’t be included in your app’s release zip file.

After that, you can deploy the app for the first time with:

[php]$ grunt push
$ grunt reset</pre>
[/php]

Please ensure that your Firefox OS phone has the Remote Debugging option enabled! This is set in the Settings app, thenDevice Information > More Information > Developer

Things and tools you need to develop apps for Firefox OS

Firefox Nightly: to quickly test your apps in a browser. It’s quite nice once you enable the Responsive Design View (atTools / Web Developer).
Firefox OS Simulator: as an extension for Firefox Nightly.
A Firefox OS phone: of the two available models for developers, we like Keon more (and it’s cheaper!).

Some tutorials and documentation you can read:

Workflow

Let’s see an example of how development works with these scaffold and tools.

A first run

To see the current status of our app, run:

[php]$ grunt server</pre>
[/php]

Now open [0.0.0.0:9000] with Firefox Nightly, enable Responsive Design View (⌥⌘M if you’re on a Mac) and choose the size 320×480, which is the resolution that Keon has. However, note that there will be more devices with different solutions, so you shouldn’t use a fixed size design.

You should see something similar to this:

Edit index.html

We’re going to change our app’s header. Edit app/index.html and you will find this piece of code in it:

[php]<section role="region">
<header>
<h1>My Firefox OS App</h1>
</header>
…
</section></pre>
[/php]

The fancy role=”region” in <section> (and role=”application” in <body>) is because we are using the Headers Building Block from Gaia. That’s how it gets rendered with the orange gradient and the shadow.

Let’s change the text in <h1> for something else:

[php]<h1>Hello!</h1></pre>
[/php]

Refresh your browser and…

Change the CSS

We’re going to make some changes to the CSS so it looks prettier. Included in the project is a Sass pipeline, so instead of writing raw CSS we can use awesome Sass.

Edit app/styles/main.sass so it looks like this:

[php]html
font-size: 62.5%

body
margin: 0
padding: 0
font: 1.6rem/2.2rem MozTT, sans-serif

p
margin: 1rem</pre>
[/php]

That basically adjusts the base font size (since all Gaia’s Building Blocks use rem units, which refer to this size), and change the font family to MozTT, which is included on Firefox OS (you can download it for your computer).

If you take a look at the console, you can see how the Sass file changed, and that Grunt automatically run the sass:dev task to recompile the final CSS stylesheet that is included in app/index.html.

[php]>> File "app/styles/main.sass" changed.
Running "sass:dev" (sass) task
Done, without errors.</pre>
[/php]

A bit of JavaScript…

Since we’re using Backbone as a MVC framework, we’ll have models, views and (possibly) controllers, and the differents views will be shown and swapped in the same HTML file. The logic that controls which view is shown resides in one Backbone object called Router. There’s this snippet in app/scripts/router.js:

[php]Backbone.Router.extend({
routes: {
”: ‘hello’
},
hello: function () {
var view = new HelloView({el: $(‘#hello’)});
view.render();
}
});</pre>
[/php]

There we’re defining a route at the root (hence the empty string ”, that will execute the method hello). As you can see that method creates a new instance of HelloView and calls its render method. So this is what will get executed automatically when we load the page (or open the app in the device).

Let’s open that view to take a look: app/scripts/views/hello.js:

[php]Backbone.View.extend({
template: templates.hello,
render: function () {
$(this.el).html(this.template({ someone: ‘World’ }));
}
});</pre>
[/php]

Here we’re telling the view to use a Handlebars template named hello.hbs (we can ommit the extension). The render method, that we’re calling from the Router, just renders that template and puts it as the content of the this.el node that we passed to the view when we instantiated it (in our case, a paragraph with the ID #hello).

The Object that we’re passing the template rendering method is the data the template will use. Let’s change that and add a new value:

[php]render: function () {
$(this.el).html(this.template({
someone: ‘World’,
message: ‘Lorem ipsum’
}));
}</pre>
[/php]

Now we’ll edit the template itself (`app/scripts/templates/hello.hbs’) to use this new data.

[php]Hello <strong>{{someone}}</strong>!
Here’s a message for you: <q>{{message}}</q>.</pre>
[/php]

Reload the page and see the new template in action.

Tests

Let’s do a bit of testing. All specs files are located in test/specs. Let’s create a new file to test HelloView: test/specs/hello.js.

[php]define([
‘zepto’,
‘views/hello’
], function ($, HelloView) {
‘use strict’;

describe(‘HelloView’, function () {
it(‘renders a custom message’, function () {
var view = new HelloView({el: $(‘#placeholder’)});
view.render();
chai.expect($(view.el).text()).to.equal(‘Lorem ipsum’);
});
});
});</pre>
[/php]

In this sample test, we created a new instance of HelloView, passing a #placeholder as the root element for that view (we’ll have to add it later to our test/index.html). When we call view.render(), the template content will be rendered inside this #placeholder node. Then, we have our expectation: that the q tag inside the view must have Lorem ipsum as content.

Let’s do the changes we need to make this work at test/index.html. Basically we need to add a new <div> with ID #placeholder (so we can render all of our views there), and then load the test within require:

[php]…
<div id="mocha"></div>
<!– to render views –>
<div id="placeholder" style="display:none"></div>
…
<script type="text/javascript">
require([
// …
‘spec/hello’
], function () {
mocha.run(); // run the tests with mocha
});
</script></pre>
[/php]

Time to run the tests! We can run the tests in our shell:

[php]$ grunt bash
…
Testing: http://0.0.0.0:9002/index.html
sample test
✓ just works
HelloView
✓ renders a custom message
2 tests complete (108 ms)
>> 2 passed! (0.11s)

Done, without errors.</pre>
[/php]

And we can also launch them within a browser, so we can test our app in Firefox:

[php]$ grunt server:test</pre>
[/php]

Now load 0.0.0.0:9002 and see the tests working.

Deploying the app

Now let’s try the app in the phone. Connect your Firefox OS device to your computer, and make sure that Remote Debugging is enabled. Remember that you can check this in the Settings app, then Device Information > More Information > Developer.

Now run this tasks:

[php]$ grunt push
$ grunt reset</pre>
[/php]

A prompt will appear in your phone asking if you want to accept the communication (say yes). Then Boot2Gecko will get restarted after a few seconds, and there it is! Your very own shiny app in Firefox OS :)

The first task, push will create a zip file with a build of the app, and will send it to the device. The reset task is only necessary the first time you copy the app and it will make the app’s icon to show up in the Home screen.

You can also try your app in the Firefox OS Simulator inside Firefox Nightly. Go to Tools > Web Developer > Firefox OS Simulator.