26 November 2013: By The Telefonica Digital PDI UK team

The initial tree directory looks like this:

[php]
├── .bowerrc
├── .jshintrc
├── .tmp/
├── components/
├── Gruntfile.js
├── README.md
├── app/
│   ├── icons/
│   ├── images/
│   ├── index.html
│   ├── manifest.webapp
│   ├── scripts/
│   └── styles/
│   ├── gaiabb/
│   └── main.sass
├── bower.json
├── node_modules/
├── package.json
└── test
├── components -> ../app/components
├── index.html
├── lib/
├── main.js
├── scripts -> ../app/scripts
└── spec/[/php]

Long story short: put your JavaScript files in app/scripts, your Sass stylesheets in app/styles and your specs in test/specs.

Grunt

Grunt is a Node tool for automation. I cannot imagine front-end development without it anymore, so if you’ve never used before, be prepared to discover a brand new world of possibilities :)

Grunt allows you to define tasks in a file named Gruntfile.js. You can create your own tasks, or download grunt plugins that other people have already cooked for you.

In this project, we use tasks to automate things like compiling Sassfiles, deploying the app to a Firefox OS device, analyse our JavaScript files with a linter, run a local static HTTP server, etc.

For instance, you can try this:

• Execute $ grunt server
• Open http://0.0.0.0:9000

You can read the tasks documentation in the README.md file at the root of your app.

Although at first the Gruntfile.js can be a bit daunting, you will want to edit it to suit your needs and add more tasks, so please do take a look at it.

Bower

Bower is another Node tool to include and manage 3rd-party library dependencies in your project. Think of it as a Gemfile or a pip’sRequirements.txt.

Your bower dependencies are included in a JSON file named Bower.json. There you can see a section that looks like this:

[php]"devDependencies": {
"backbone": "~1.0.0",
"underscore": "~1.4.4",
"handlebars.js": "~1.0.0",
"requirejs": "~2.1.6",
"zepto": "~1.0.0"
}[/php]

Those are our dependencies. From there you can infer that the app uses a stack with Backbone / Underscore / Zepto plus RequireJS to handle dependencies and Handlebars. You can install more libraries and automatically update this file with:

[php]bower install somelibrary –save-dev[/php]

Mocha tests

The test library included is Mocha, that allows us to write our specs in a clean way. As support libraries, Sinon has been included to create mocks and stubs, and Chai is used for expectations.

You can see a sample test in test/specs/sample.js:

[php]describe(‘sample test’, function () {
it(‘just works’, function () {
chai.expect(2 + 2).to.equal(4);
});
});[/php]

If you add more files to specs, be sure to edit test/index.html to add them to the list included by RequireJS (look near the bottom of the file):

[php]<script type="text/javascript">
require([
‘main’,
// include spec files here
‘spec/sample’
], function () {
mocha.run(); // run the tests with mocha
});
</script>[/php]

You can run your tests in the console with grunt:

[php]$ grunt test[/php]

This will use PhantomJS, which is not ideal for Firefox OS development because it’s Webkit-based. However, it’s the only way to launch the tests in a console, so you can setup git pre-commit hooks, or a job in Jenkins, etc.

You do want run the tests in a Firefox Nightly browser:

[php]$ grunt server:test[/php]

Now open 0.0.0.0:9002.

Gaia’s Building Blocks

Gaia’s Building Blocks is a set of CSS + HTML files with UI widgets used in Gaia (the top layer on top of Boot2Gecko in Firefox OS). It’s what system apps use, so if you’d like that look for your app, you can use them.

The Building Blocks are located in app/styles/gaiabb. There you can find a bunch of CSS files and some directories. If you open a directory you will find the images that block use plus an HTML with examples.

At the end, all the blocks will be minified in a single all.css file, that is the one that you are including in your index.html. If you delete some blocks, or add new ones, this all.css file will be updated automatically.

The blocks that have been included are the ones tagged as stable. You can download all blocks from Building Firefox OS and include the ones you want simply by copying the related CSS and directory folder to app/styles/gaiabb.

Sass

Because if you’re writing CSS and you’re not using Sass, you are wrong.

Any *.sass file you drop in app/styles/sass will be compiled. Remember that you can have partials (Sass files that start with _), that would be included in other Sass files, and these partials won’t be compiled to their own CSS. Let’s try this: create a _partial.sass file inapp/styles and put something on it:

[php]a
color: red[/php]

Now edit app/styles/main.sass to include it at the top of the file:

[php]@import _partial
// more styles here…[/php]

Now build the app with grunt and inspect the generated CSS file:

[php]$ grunt build
$ ls build/styles
gaiabb main.css
$ cat build/styles/main.css
a{color:red}body{margin:0;padding:0}[/php]

JavaScript linter (JSHint)

A linter is a tool that analyses your source code and tells you whether you have syntax errors (handy to know you’ve made a mistake without having to reload your browser) and, most important, checks the quality of your code.

We’re using JSHint for this, and you can launch it with grunt:

[php]$ grunt jshint[/php]

The linter will also analyse your source every time you launch a local web server, run your tests, build a release, etc. so you can be sure you are not screwing up :)

You can customise the rules used by JSHint by editing the .jshintrc file. We have been quite radical and included most of the fussy rules. This can be a bit annoying sometimes, but it pays off in cleaner, less buggy code.

Quick note. Don’t change the 80 characters per line rule. Do yourself and your eyesight a favor: keep this rule and increase the font size of your editor to something about 26pt. You should be able to fit 80 characters line and 20+ lines of code. More than enough to program, and much more healthier for your eyes.

The app framework

Since we chose to include an app MVC framework, we can see that bower has installed the following stack:

• Backbone + Zepto + Underscore
• RequireJS
• Handlebars

You probably have heard that you really need to optimise your JavaScript in order to develop apps for Firefox OS. While this is true, you are still allowed to use some libraries to help you out (as long as they don’t use eval and blow up a security error in the device).

The libraries that the generator has included are lightweight and reasonably fast. Backbone is a compact, minimalistic and light MVC framework. Zepto has been included as a jQuery alternative, because it works and it’s just 27KB. The other Backbone dependency isUnderscore, which shouldn’t be a burden and it comes quite handy to do functional programming.

Now, we are not using Underscore’s templates, but Handlebars. Handlebars templates are logic-less, can be precompiled (so they’re fast and you are not getting those security errors with eval that we’ve talk about before) and are compatible with Mutache syntax. You can find a sample template in app/scripts/templates/sample.hbs.

And about RequireJS… it’s the easiest way to manage JavaScript dependencies in a project.

If you’re new to Backbone, there is an introductory tutorial called Hello Backbone.js so you can get a grasp on whether you like it or not.

Note that you can skip this whole framework by answering NO when launching the generator. In that case, you would have a vanilla JavaScript application.