mozilla

Revision 474001 of Your first app

  • Revision slug: Web/Apps/Quickstart/Build/Your_first_app
  • Revision title: Your first app
  • Revision id: 474001
  • Created:
  • Creator: chrisdavidmills
  • Is current revision? No
  • Comment
Tags: 

Revision Content

Open web apps give web developers exactly what they've wanted for years: a cross-platform environment dedicated to installable apps created with just HTML, CSS, and JavaScript (Firefox OS being the first dedicated open web apps platform). This guide aims to get you up and running quickly with a basic architecture and build instructions so that you can create the next great app!

If you'd like to follow along with this guide, you can download the quick start app.

App Structure

Packaged vs. Hosted Apps

There are two types of Firefox OS apps: packaged and hosted. Packed apps are essentially a zip file containing all of of an apps assets: HTML, CSS, JavaScript, images, manifest, etc. Hosted apps are run from a server at a given domain, just like a standard website. Both app types require a valid manifest. When it comes time to list your app on the Firefox Marketplace, you will either upload your app as a zip file or provide the URL to where your hosted app lives.

Made in partnership with our friends at Treehouse: Check them out!

 

For the purposes of this guide, you'll be creating a hosted app which will live at your localhost address. Once your app is ready to list on the Firefox Marketplace, you can make the decision to bundle as a packed app or launch as a hosted app.

App Manifests

Every Firefox app requires an manifest.webapp file at the app root. The manifest.webapp file provides important information about the app, like version, name, description, icon location, locale strings, domains the app can be installed from, and much more (Only the name and description are required). The simple manifest included within the app template looks like:

{
    "version": "0.1",
    "name": "Your App",
    "description": "Your new awesome Open Web App",
    "launch_path": "/index.html",
    "icons": {
        "16": "/img/icons/mortar-16.png",
        "48": "/img/icons/mortar-48.png",
        "128": "/img/icons/mortar-128.png"
    },
    "developer": {
        "name": "Your Name",
        "url": "http://yourawesomeapp.com"
    },
    "installs_allowed_from": ["*"],
    "locales": {
        "es": {
            "description": "Su nueva aplicación impresionante Open Web",
            "developer": {
                "url": "http://yourawesomeapp.com"
            }
        },
        "it": {
            "description": "Il vostro nuovo fantastico Open Web App",
            "developer": {
                "url": "http://yourawesomeapp.com"
            }
        }
    },
    "default_locale": "en",
    "permissions": {
        "systemXHR": {}
    }
}
Made in partnership with our friends at Treehouse Check them out!

 

More specific details can be added as the project gets closer to completion, as is the case with most Firefox OS apps. A basic manifest will do to get started.

App Layout & Design

Responsive design has become increasingly important as more screen resolutions become standard on different devices. Even if your app targets only Firefox OS, it's important to remember that Firefox OS can be installed on a variety of devices which use different screen resolutions. CSS media queries provide a means to adapt layout to device:

/* The following are examples of different CSS media queries */

/* Basic desktop/screen width sniff */
@media only screen and (min-width : 1224px) {
  /* styles */
}

/* Traditional iPhone width */
@media
  only screen and (-webkit-min-device-pixel-ratio : 1.5),
  only screen and (min-device-pixel-ratio : 1.5) {
  /* styles */
}

/* Device settings at different orientations */
@media screen and (orientation:portrait) {
  /* styles */
}
@media screen and (orientation:landscape) {
  /* styles */
}

 

There are many JavaScript and CSS frameworks available to aid in responsive design and mobile app development (Bootstrap, etc.); choose the framework(s) that best fit your app and development style.

One nice utility is Mozilla's mortar. Mortar doesn't provide responsive design help, but does provide app templates a few JavaScript utilities to aid in Firefox OS mobile development, like zepto.js (a light alternative to jQuery) and a utility to install your app on the Firefox OS Simulator. This quick start guide fits you with mortar's most basic layout template:

<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8">

    <title>My App</title>
    <meta name="description" content="">
    <meta name="viewport" content="width=device-width">

    <!-- Place favicon.ico in the root directory -->

    <link rel="stylesheet" href="css/app.css">
  </head>
  <body>
    <!-- Use this installation button to install locally without going
         through the marketpace (see app.js) -->
    <button id="install-btn">Install</button>

    <!-- Write your application here -->



    <!-- Using require.js, a module system for javascript, include the
         js files. This loads "init.js", which in turn can load other
         files, all handled by require.js:
         http://requirejs.org/docs/api.html#jsfiles -->
    <script type="text/javascript" data-main="js/init.js" src="js/lib/require.js"></script>
  </body>
</html>

 

Feel free to modify the structure set forth by mortar — the snippet above should get you going. Note that all JavaScript code must be in separate .js files; no inline, scripting is allowed.

Web APIs

JavaScript APIs are being created and enhanced as quickly as devices are. Mozilla's WebAPI effort brings dozens of standard mobile features to JavaScript APIs. A list of device support and status is available on the WebAPI page. Of course JavaScript feature detection is still the best practice:

// If this device supports the vibrate API...
if('vibrate' in navigator) {
    // ... vibrate for a second
    navigator.vibrate(1000);
}

In this very basic app template we'll modify the display style of a DIV based on changes in the device's battery state:

// Create the battery indicator listeners
(function() {
  var battery = navigator.battery || navigator.mozBattery || navigator.webkitBattery,
      indicator, indicatorPercentage;

  if(battery) {
    indicator = document.getElementById('indicator'),
    indicatorPercentage = document.getElementById('indicator-percentage');

    // Set listeners for changes
    battery.addEventListener('chargingchange', updateBattery);
    battery.addEventListener('levelchange', updateBattery);

    // Update immediately
    updateBattery();
  }

  function updateBattery() {
    // Update percentage width and text
    var level = (battery.level * 100) + '%';
    indicatorPercentage.style.width = level;
    indicatorPercentage.innerHTML = 'Battery: ' + level;
    // Update charging status
    indicator.className = battery.charging ? 'charging' : '';
  }
})();

 

 

In the code sample above, once you confirm that the Battery API is supported, you can add event listeners for chargingchange and levelchange to update the element's display.

Check the WebAPI page frequently to keep up to date with device API statuses!

WebRT APIs (Permissions-based APIs)

There are a number of WebAPIs which are available but require permissions for that specific feature to be enabled. Apps may register permission requests within the manifest.webapp file:

// New key in the manifest: "permissions"
// Request access to any number of APIs
// Here we request permissions to the systemXHR API
"permissions": {
    "systemXHR": {}
}

 

Once you've installed your app on Firefox OS Simulator, open the Settings app, select App Permissions, select your app, and enable permissions as desired. It's important to note that not all Web APIs have been implemented within the Firefox OS Simulator.

Tools & Testing

Testing is incredibly important when supporting mobile devices. There are many options for testing FirefoxOS apps:

Firefox OS Simulator

Installing and using the Firefox OS Simulator is the easiest way to get up and running with your app. After installed the simulator is accessible via the Tools -> Web Developer -> Firefox OS Simulator menu. The simulator launches with a JavaScript console so that you may debug your application from within the simulator!

Unit Testing

Unit tests are extremely valuable when testing on different devices and builds. jQuery's QUnit is a popular client-side testing utility, but you can use any set of testing tools you'd like.

Installing Firefox OS on a Device

Since Firefox OS is an open source platform, code and tools are available to build and install Firefox OS on your own device. Build and installation instructions can be found on MDN. Firefox OS preview devices will be available via Geeksphone soon.

App Submission and Distribution

Once your app is complete, it can be submitted to the Firefox Marketplace. Your app's manifest will be validated and you may choose which devices your app will support (i.e. Firefox OS, Desktop Firefox, Firefox Mobile, Firefox Tablet). Once validated you may add additional details about your app (screenshots, descriptions, price, etc.) and officially submit the app for listing within the Marketplace. Once approved your app is available to the world for purchase and installation.

More Marketplace & Listing Information

  1. Submitting an App to the Firefox OS Marketplace
  2. Marketplace Review Criteria
  3. App Submission Video Walkthrough

Revision Source

<article>
  <p>Open web apps give web developers exactly what they've wanted for years: a cross-platform environment dedicated to installable apps created with just HTML, CSS, and JavaScript (Firefox OS being the first dedicated open web apps platform). This guide aims to get you up and running quickly with a basic architecture and build instructions so that you can create the next great app!</p>
  <p>If you'd like to follow along with this guide, you can <a href="https://github.com/mozilla/firefoxos-quick-start/archive/master.zip">download the quick start app</a>.</p>
  <h2 id="App_Structure">App Structure</h2>
  <h3 id="Packaged_vs._Hosted_Apps">Packaged vs. Hosted Apps</h3>
  <p>There are two types of Firefox OS apps: <code>packaged</code> and <code>hosted</code>. Packed apps are essentially a <code>zip</code> file containing all of of an apps assets: HTML, CSS, JavaScript, images, manifest, etc. Hosted apps are run from a server at a given domain, just like a standard website. Both app types require a valid manifest. When it comes time to list your app on the Firefox Marketplace, you will either upload your app as a zip file or provide the URL to where your hosted app lives.</p>
  <p><iframe allowfullscreen="" frameborder="0" height="270" src="https://www.youtube.com/embed/Q7x-B13y33Q/?feature=player_detailpage" width="480"></iframe></p>
  <div class="video-caption">
    <span>Made in partnership with our friends at Treehouse:</span> <a class="button" href="http://teamtreehouse.com/?cid=1154">Check them out!</a>
    <hr />
  </div>
  <p>&nbsp;</p>
  <p>For the purposes of this guide, you'll be creating a hosted app which will live at your <code>localhost</code> address. Once your app is ready to list on the Firefox Marketplace, you can make the decision to bundle as a packed app or launch as a hosted app.</p>
  <h3 id="App_Manifests">App Manifests</h3>
  <p>Every Firefox app requires an manifest.webapp file at the app root. The <code><a href="https://marketplace.firefox.com/developers/docs/manifests">manifest.webapp</a></code> file provides important information about the app, like version, name, description, icon location, locale strings, domains the app can be installed from, and much more (Only the name and description are required). The simple manifest included within the app template looks like:</p>
  <pre>
<code>{
    "version": "0.1",
    "name": "Your App",
    "description": "Your new awesome Open Web App",
    "launch_path": "/index.html",
    "icons": {
        "16": "/img/icons/mortar-16.png",
        "48": "/img/icons/mortar-48.png",
        "128": "/img/icons/mortar-128.png"
    },
    "developer": {
        "name": "Your Name",
        "url": "http://yourawesomeapp.com"
    },
    "installs_allowed_from": ["*"],
    "locales": {
        "es": {
            "description": "Su nueva aplicación impresionante Open Web",
            "developer": {
                "url": "http://yourawesomeapp.com"
            }
        },
        "it": {
            "description": "Il vostro nuovo fantastico Open Web App",
            "developer": {
                "url": "http://yourawesomeapp.com"
            }
        }
    },
    "default_locale": "en",
    "permissions": {
        "systemXHR": {}
    }
}</code></pre>
  <iframe allowfullscreen="" frameborder="0" height="385" src="//www.youtube.com/embed/dgAUgHQOm8M?wmode=transparent" width="685"></iframe>
  <div class="video-caption">
    <span>Made in partnership with our friends at Treehouse</span> <a class="button" href="http://teamtreehouse.com/?cid=1154">Check them out!</a>
    <hr />
  </div>
  <p>&nbsp;</p>
  <p>More specific details can be added as the project gets closer to completion, as is the case with most Firefox OS apps. A basic manifest will do to get started.</p>
  <h2 id="App_Layout_.26_Design">App Layout &amp; Design</h2>
  <p>Responsive design has become increasingly important as more screen resolutions become standard on different devices. Even if your app targets only Firefox OS, it's important to remember that Firefox OS can be installed on a variety of devices which use different screen resolutions. <a href="//developer.mozilla.org/docs/CSS/Media_queries">CSS media queries</a> provide a means to adapt layout to device:</p>
  <pre>
<code>/* The following are examples of different CSS media queries */

/* Basic desktop/screen width sniff */
@media only screen and (min-width : 1224px) {
  /* styles */
}

/* Traditional iPhone width */
@media
  only screen and (-webkit-min-device-pixel-ratio : 1.5),
  only screen and (min-device-pixel-ratio : 1.5) {
  /* styles */
}

/* Device settings at different orientations */
@media screen and (orientation:portrait) {
  /* styles */
}
@media screen and (orientation:landscape) {
  /* styles */
}</code></pre>
  <p>&nbsp;</p>
  <p>There are many JavaScript and CSS frameworks available to aid in responsive design and mobile app development (<a href="http://twitter.github.com/bootstrap">Bootstrap</a>, etc.); choose the framework(s) that best fit your app and development style.</p>
  <p>One nice utility is Mozilla's <a href="https://github.com/mozilla/mortar">mortar</a>. Mortar doesn't provide responsive design help, but does provide app templates a few JavaScript utilities to aid in Firefox OS mobile development, like <a href="http://zeptojs.com">zepto.js</a> (a light alternative to jQuery) and a utility to install your app on the Firefox OS Simulator. This quick start guide fits you with mortar's most basic layout template:</p>
  <pre>
<code>&lt;!DOCTYPE html&gt;
&lt;html&gt;
  &lt;head&gt;
    &lt;meta charset="utf-8"&gt;

    &lt;title&gt;My App&lt;/title&gt;
    &lt;meta name="description" content=""&gt;
    &lt;meta name="viewport" content="width=device-width"&gt;

    &lt;!-- Place favicon.ico in the root directory --&gt;

    &lt;link rel="stylesheet" href="css/app.css"&gt;
  &lt;/head&gt;
  &lt;body&gt;
    &lt;!-- Use this installation button to install locally without going
         through the marketpace (see app.js) --&gt;
    &lt;button id="install-btn"&gt;Install&lt;/button&gt;

    &lt;!-- Write your application here --&gt;



    &lt;!-- Using require.js, a module system for javascript, include the
         js files. This loads "init.js", which in turn can load other
         files, all handled by require.js:
         http://requirejs.org/docs/api.html#jsfiles --&gt;
    &lt;script type="text/javascript" data-main="js/init.js" src="js/lib/require.js"&gt;&lt;/script&gt;
  &lt;/body&gt;
&lt;/html&gt;</code></pre>
  <p>&nbsp;</p>
  <p>Feel free to modify the structure set forth by mortar — the snippet above should get you going. Note that all JavaScript code must be in separate <code>.js</code> files; no inline, scripting is allowed.</p>
  <h2 id="Web_APIs">Web APIs</h2>
  <p>JavaScript APIs are being created and enhanced as quickly as devices are. Mozilla's <a href="https://wiki.mozilla.org/WebAPI">WebAPI</a> effort brings dozens of standard mobile features to JavaScript APIs. A list of device support and status is available on the <a href="https://wiki.mozilla.org/WebAPI">WebAPI</a> page. Of course JavaScript feature detection is still the best practice:</p>
  <pre>
<code>// If this device supports the vibrate API...
if('vibrate' in navigator) {
    // ... vibrate for a second
    navigator.vibrate(1000);
}</code></pre>
  <p>In this very basic app template we'll modify the display style of a <code>DIV</code> based on changes in the device's battery state:</p>
  <pre>
<code>// Create the battery indicator listeners
(function() {
  var battery = navigator.battery || navigator.mozBattery || navigator.webkitBattery,
      indicator, indicatorPercentage;

  if(battery) {
    indicator = document.getElementById('indicator'),
    indicatorPercentage = document.getElementById('indicator-percentage');

    // Set listeners for changes
    battery.addEventListener('chargingchange', updateBattery);
    battery.addEventListener('levelchange', updateBattery);

    // Update immediately
    updateBattery();
  }

  function updateBattery() {
    // Update percentage width and text
    var level = (battery.level * 100) + '%';
    indicatorPercentage.style.width = level;
    indicatorPercentage.innerHTML = 'Battery: ' + level;
    // Update charging status
    indicator.className = battery.charging ? 'charging' : '';
  }
})();</code></pre>
  <p>&nbsp;</p>
  <p>&nbsp;</p>
  <p>In the code sample above, once you confirm that the <a href="https://developer.mozilla.org/en-US/docs/DOM/window.navigator.battery">Battery API</a> is supported, you can add event listeners for <code>chargingchange</code> and <code>levelchange</code> to update the element's display.</p>
  <p>Check the <a href="https://wiki.mozilla.org/WebAPI">WebAPI</a> page frequently to keep up to date with device API statuses!</p>
  <h2 id="WebRT_APIs_(Permissions-based_APIs)">WebRT APIs (Permissions-based APIs)</h2>
  <p>There are a number of WebAPIs which are available but require permissions for that specific feature to be enabled. Apps may register permission requests within the <code>manifest.webapp</code> file:</p>
  <pre>
<code>// New key in the manifest: "permissions"
// Request access to any number of APIs
// Here we request permissions to the systemXHR API
"permissions": {
    "systemXHR": {}
}</code></pre>
  <p>&nbsp;</p>
  <p>Once you've installed your app on Firefox OS Simulator, open the <code>Settings</code> app, select <code>App Permissions</code>, select your app, and enable permissions as desired. It's important to note that not all Web APIs have been implemented within the Firefox OS Simulator.</p>
  <h2 id="Tools_.26_Testing">Tools &amp; Testing</h2>
  <p>Testing is incredibly important when supporting mobile devices. There are many options for testing FirefoxOS apps:</p>
  <h3 id="Firefox_OS_Simulator">Firefox OS Simulator</h3>
  <p>Installing and using the <a href="https://marketplace.firefox.com/developers/docs/firefox_os_simulator">Firefox OS Simulator</a> is the easiest way to get up and running with your app. After installed the simulator is accessible via the Tools -&gt; Web Developer -&gt; Firefox OS Simulator menu. The simulator launches with a JavaScript console so that you may debug your application from within the simulator!</p>
  <h3 id="Unit_Testing">Unit Testing</h3>
  <p>Unit tests are extremely valuable when testing on different devices and builds. jQuery's <a href="http://qunitjs.com">QUnit</a> is a popular client-side testing utility, but you can use any set of testing tools you'd like.</p>
  <h3 id="Installing_Firefox_OS_on_a_Device">Installing Firefox OS on a Device</h3>
  <p>Since Firefox OS is an open source platform, code and tools are available to build and install Firefox OS on your own device. Build and installation instructions can be found on <a href="https://developer.mozilla.org/en-US/docs/Mozilla/Firefox_OS/Platform">MDN</a>. Firefox OS preview devices will be available via <a href="http://www.geeksphone.com">Geeksphone</a> soon.</p>
  <h2 id="App_Submission_and_Distribution">App Submission and Distribution</h2>
  <p>Once your app is complete, it can be <a href="https://marketplace.firefox.com/developers/submit/app/manifest">submitted</a> to the <a href="https://marketplace.firefox.com">Firefox Marketplace</a>. Your app's manifest will be validated and you may choose which devices your app will support (i.e. Firefox OS, Desktop Firefox, Firefox Mobile, Firefox Tablet). Once validated you may add additional details about your app (screenshots, descriptions, price, etc.) and officially submit the app for listing within the Marketplace. Once approved your app is available to the world for purchase and installation.</p>
  <h3 id="More_Marketplace_.26_Listing_Information">More Marketplace &amp; Listing Information</h3>
  <ol>
    <li><a href="//developer.mozilla.org/docs/Apps/Submitting_an_app">Submitting an App to the Firefox OS Marketplace </a></li>
    <li><a href="/developers/docs/review">Marketplace Review Criteria </a></li>
    <li><a href="http://s.vid.ly/embeded.html?link=8k2n4w&amp;autoplay=false">App Submission Video Walkthrough </a></li>
  </ol>
</article>
Revert to this revision