Revision Content

Creating a weather app with templates

We have created the Open Web App Bootstrap templates to help you get started writing an Open Web App. These templates are HTML/CSS/JS projects that are already set up to get you started writing your app quickly.

The code name for the Open Web App Bootstrap templates is Mortar. There is only one template available right now: the "app-stub" template. This is a basic template that includes jQuery, require.js, volo, Mozilla Marketplace libraries, and other helpful things. A game template and others will be available soon.

What you need

Setup

To get started, simply download the template. Alternatively, run this command (wget is a GNU Project utility):

$ wget http://mozilla.github.com/mortar/builds/app-stub.zip

Let's unzip the template into your project directory.

$ unzip app-stub.zip
$ mv app-stub weatherme
$ cd weatherme

Before we do any work, we want to make it a Git repository:

$ git init
$ git add -A
$ git commit -m 'initial'

You will also need volo, so if you don't already have it (npm is a utility that comes with node.js):

$ npm install -g volo

Volo is a tool for running tasks for your project so that you can quickly test, optimize, and deploy your code with a single command.

Note: If you already have volo installed and you get an error with volo commands, try getting the latest version of volo.

Development

Ok, now we're ready to code. But wait, where are the HTML/CSS/JS files? Here's what the directory structure looks like:

README.textile
package.json
tools
volofile
www

The actual project is inside the www folder. The other files provide the capability for testing and deploying your code, which we will get to later.

If you look in www, you will see a lot of stuff there. Most of this came from the HTML5 Boilerplate project, but it has been heavily customized for writing Open Web Apps.

HTML

To add HTML code, open up www/index.html. The first thing you should do is set a title and description in the title and meta tags, and then add your app's HTML in the body tag. Don't add any CSS or JavaScript here, we'll get to that later.

You can see the code that was added for weatherme here. We're using Twitter Bootstrap, so you'll see a navigation element and some buttons.

Let's check the HTML in the browser. Run this command from the root of the project:

$ volo serve

This fires up a simple server on your local computer, and you can see your project by opening http://localhost:8008.

JavaScript

Next, let's add a JavaScript library. A good one is underscore.js, and we can get it with a simple volo command:

$ volo add underscore

The add command finds the project on GitHub and fetches it (you can also pass it a URL). It is now available as a library that we can import with require.js.

Next, let's write some JavaScript to power the app. I'm using Yahoo's weather API to get forecast data. Open up www/js/app.js and you'll see JavaScript already in there. This sets up require.js and includes jQuery and other libraries already.

You'll see the following statement:

define("app", function(require) {

This is defining a require.js module, and you need to write your code within this function. You can see the JavaScript code for weatherme here.

If you want to use a JavaScript library, you need to import it first. We added underscore.js to our project above, so to use it we would write:

var _ = require('underscore');

With require.js, never load in JavaScript with <script> tags. There might be a few exceptions, but everything should be imported with require. This helps modularity, separates concerns, and makes it easy to minimize and concatenate everything for deployment.

Since weatherme uses the Twitter Bootstrap tab component, we need to include its JavaScript. Add this line:

require('bootstrap/tab');

You don't care about the return value because it modifies the jQuery object. You can view the rest of the JavaScript for weatherme on GitHub.

CSS

Now, for CSS. Open up www/css/app.css and you'll see that it imports defaults.css. Feel free to open up defaults.css and modify the defaults. Since we are using Twitter Bootstrap, uncomment the following line:

@import "bootstrap.css";

That will include the CSS for Twitter Bootstrap components. We don't need the responsive CSS, so we will leave that commented out. When we build the app for deployment, this will all be inlined into a single CSS file.

Write the rest of the CSS for your app in this file. You can view the weatherme CSS here.

Now that I've written HTML, CSS, and JavaScript, it's time to test it! Fire up the serve command again:

Deployment

Before we deploy, we need to customize manifest.webapp. Open up the file in www change the name, description, and other properties. If you're going to host it on github, make sure to set the launch_path setting to /<project-name>/ instead of just /.

When you are ready to deploy, build your app (from the root directory):

volo build

This creates a www-built directory with all JavaScript and CSS concatenated and minified. If you want to test this, run the serve command with the base argument:

volo serve base=www-built

If you want an appcache so that your app can run offline, volo has a command to generate it for you. All you need to do is:

volo appcache

And it will create it in the www-built directory (building your app if it hasn't been yet). That's it! All of your files will be cached and usable offline.

Lastly, volo has a command for deploying to GitHub. We recommend hosting your app on GitHub because it is easy and stable. You can't do this if you need a server-side component, but if it's all client-side you should use GitHub Pages. Just type:

volo ghdeploy

And volo will create a repo for you if it doesn't exist yet and push to the gh-pages branch, which tells github to create your page at <username>.github.com/<project>. You app is now live!

When you make future changes, you must first build your app (volo build) and then deploy it (volo ghdeploy). The ghdeploy command does not automatically build your app.

Revision Source

<h2 id="Creating_a_weather_app_with_templates">Creating a weather app with templates</h2>
<p>This tutorial tells you how to build an example app called&nbsp;<a href="http://jlongster.github.com/weatherme/" title="http://jlongster.github.com/weatherme/">weatherme</a>.</p>
<p>We have created the Open Web App Bootstrap templates to help you get started writing an Open Web App. These templates are HTML/CSS/JS projects that are already set up to get you started writing your app quickly.</p>
<p>The code name for the Open Web App Bootstrap templates is <a href="https://github.com/mozilla/mortar/" title="https://github.com/mozilla/mortar/">Mortar</a>. There is only one template available right now: the "app-stub" template. This is a basic template that includes jQuery, require.js, volo, Mozilla Marketplace libraries, and other helpful things. A game template and others will be available soon.</p>
<p>The weatherme app is built with the app-stub template.</p>
<h3 id="What_you_need">What you need</h3>
<ul>
<li><a href="http://nodejs.org/" title="http://nodejs.org/">Node.js</a> (needed for volo and other tools described below)</li>
<li><a href="http://git-scm.com/" title="/en-US/docs/Githttp://git-scm.com/">Git</a></li>
<li><a href="https://github.com/" title="https://github.com/">GitHub</a> account (a free account is enough)</li>
<li><a href="https://github.com/mozilla/mortar/" title="https://github.com/mozilla/mortar/">Mortar</a></li>
</ul>
<h3 id="Setup">Setup</h3>
<p>To get started, simply <a href="http://mozilla.github.com/mortar/builds/app-stub.zip" title="http://mozilla.github.com/mortar/builds/app-stub.zip">download the template</a>. Alternatively, run this command (wget is a GNU Project utility):</p>
<pre>
$ wget http://mozilla.github.com/mortar/builds/app-stub.zip</pre>
<p>Let's unzip the template into your project directory.</p>
<pre>
$ unzip app-stub.zip
$ mv app-stub weatherme
$ cd weatherme</pre>
<p>Before we do any work, we want to make it a Git repository:</p>
<pre>
$ git init
$ git add -A
$ git commit -m 'initial'</pre>
<p>You will also need volo, so if you don't already have it (npm is a utility that comes with node.js):</p>
<pre>
$ npm install -g volo</pre>
<p>Volo is a tool for running tasks for your project so that you can quickly test, optimize, and deploy your code with a single command.</p>
<div class="note">
<p><strong>Note:</strong> If you already have volo installed and you get an error with volo commands, try getting the latest version of volo.</p>
</div>
<h3 id="Development">Development</h3>
<p>Ok, now we're ready to code. But wait, where are the HTML/CSS/JS files? Here's what the directory structure looks like:</p>
<pre>
README.textile
package.json
tools
volofile
www</pre>
<p>The actual project is inside the <code>www</code> folder. The other files provide the capability for testing and deploying your code, which we will get to later.</p>
<p>If you look in <code>www</code>, you will see a lot of stuff there. Most of this came from the <a href="http://html5boilerplate.com/" title="http://html5boilerplate.com/">HTML5 Boilerplate</a> project, but it has been heavily customized for writing Open Web Apps.</p>
<h4 id="HTML">HTML</h4>
<p>To add HTML code, open up <a href="https://github.com/jlongster/weatherme/blob/master/www/index.html" title="https://github.com/jlongster/weatherme/blob/master/www/index.html">www/index.html</a>. The first thing you should do is set a title and description in the <code>title</code> and <code>meta</code>&nbsp;tags, and then add your app's HTML in the <code>body</code>&nbsp;tag. Don't add any CSS or JavaScript here, we'll get to that later.</p>
<p>You can see the code that was added for weatherme <a href="https://github.com/jlongster/weatherme/blob/master/www/index.html#L25" title="https://github.com/jlongster/weatherme/blob/master/www/index.html#L25">here</a>. We're using Twitter Bootstrap, so you'll see a navigation element and some buttons.</p>
<p>Let's check the HTML in the browser. Run this command from the root of the project:</p>
<pre>
$ volo serve</pre>
<p>This fires up a simple server on your local computer, and you can see your project by opening&nbsp;<a href="http://localhost:8008" title="http://localhost:8008">http://localhost:8008</a>.</p>
<h4 id="JavaScript">JavaScript</h4>
<p>Next, let's add a JavaScript library. A good one is underscore.js, and we can get it with a simple volo command:</p>
<pre>
$ volo add underscore</pre>
<p>The <code>add</code>&nbsp;command finds the project on GitHub and fetches it (you can also pass it a URL). It is now available as a library that we can import with require.js.</p>
<p>Next, let's write some JavaScript to power the app. I'm using Yahoo's <a href="http://tutorialzine.com/2012/05/weather-forecast-geolocation-jquery/" title="http://tutorialzine.com/2012/05/weather-forecast-geolocation-jquery/">weather API</a> to get forecast data. Open up <a href="https://github.com/jlongster/weatherme/blob/master/www/js/app.js" title="https://github.com/jlongster/weatherme/blob/master/www/js/app.js"><code>www/js/app.js</code></a>&nbsp;and you'll see JavaScript already in there. This sets up require.js and includes jQuery and other libraries already.</p>
<p>You'll see the following statement:</p>
<pre>
define("app", function(require) {</pre>
<p>This is defining a require.js module, and you need to write your code within this function. You can see the JavaScript code for weatherme <a href="https://github.com/jlongster/weatherme/blob/master/www/js/app.js#L19" title="https://github.com/jlongster/weatherme/blob/master/www/js/app.js#L19">here</a>.</p>
<p>If you want to use a&nbsp;JavaScript&nbsp;library, you need to import it first. We added underscore.js to our project above, so to use it we would write:</p>
<pre>
var _ = require('underscore');</pre>
<p>With require.js, never load in&nbsp;JavaScript&nbsp;with <code>&lt;script&gt;</code> tags. There might be a few exceptions, but everything should be imported with <code>require</code>. This helps modularity, separates concerns, and makes it easy to minimize and concatenate everything for deployment.</p>
<p>Since weatherme uses the Twitter Bootstrap tab component, we need to include its&nbsp;JavaScript. Add this line:</p>
<pre>
require('bootstrap/tab');</pre>
<p>You don't care about the return value because it modifies the jQuery object. You can view the rest of the&nbsp;JavaScript&nbsp;for weatherme on GitHub.</p>
<h4 id="CSS">CSS</h4>
<p>Now, for CSS. Open up <a href="https://github.com/jlongster/weatherme/blob/master/www/css/app.css" title="https://github.com/jlongster/weatherme/blob/master/www/css/app.css"><code>www/css/app.css</code></a>&nbsp;and you'll see that it imports <code>defaults.css</code>. Feel free to open up defaults.css and modify the defaults. Since we are using Twitter Bootstrap, uncomment the following line:</p>
<pre>
@import "bootstrap.css";</pre>
<p>That will include the CSS for Twitter Bootstrap components. We don't need the responsive CSS, so we will leave that commented out. When we build the app for deployment, this will all be inlined into a single CSS file.</p>
<p>Write the rest of the CSS for your app in this file. You can view the weatherme CSS <a href="https://github.com/jlongster/weatherme/blob/master/www/css/app.css" title="https://github.com/jlongster/weatherme/blob/master/www/css/app.css">here</a>.</p>
<p>Now that I've written HTML, CSS, and&nbsp;JavaScript, it's time to test it! Fire up the serve command again:</p>
<pre>
volo serve</pre>
<p>And test your app at <a href="http://localhost:8008" title="http://localhost:8008">http://localhost:8008</a>. Time to fix bugs!</p>
<h3 id="Deployment">Deployment</h3>
<p>Before we deploy, we need to customize <code>manifest.webapp</code>. Open up the file in <code>www</code> change the name, description, and other properties. If you're going to host it on github, make sure to set the <code>launch_path</code> setting to <code>/&lt;project-name&gt;/</code> instead of just <code>/</code>.</p>
<div>
When you are ready to deploy, build your app (from the root directory):</div>
<div>
&nbsp;</div>
<pre>
volo build</pre>
<div>
This creates a <code>www-built</code>&nbsp;directory with all&nbsp;JavaScript&nbsp;and CSS concatenated and minified. If you want to test this, run the serve command with the <code>base</code>&nbsp;argument:</div>
<div>
&nbsp;</div>
<pre>
volo serve base=www-built</pre>
<p>If you want an <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/offline.html" title="http://www.whatwg.org/specs/web-apps/current-work/multipage/offline.html">appcache</a> so that your app can run offline, volo has a command to generate it for you. All you need to do is:</p>
<pre>
volo appcache</pre>
<p>And it will create it in the <code>www-built</code>&nbsp;directory (building your app if it hasn't been yet). That's it! All of your files will be cached and usable offline.</p>
<p>Lastly, volo has a command for deploying to GitHub. We recommend hosting your app on&nbsp;GitHub&nbsp;because it is easy and stable. You can't do this if you need a server-side component, but if it's all client-side you should use&nbsp;GitHub&nbsp;Pages. Just type:</p>
<pre>
volo ghdeploy</pre>
<p>And volo will create a repo for you if it doesn't exist yet and push to the <code>gh-pages</code> branch, which tells github to create your page at <code>&lt;username&gt;.github.com/&lt;project&gt;</code>. You app is now live!</p>
<p>When you make future changes, you must first build your app (<code>volo build</code>) and then deploy it (<code>volo ghdeploy</code>). The ghdeploy command does not automatically build your app.</p>