Please note, this is a STATIC archive of website developer.mozilla.org from November 2016, cach3.com does not collect or store any user information, there is no "phishing" involved.

Cordova Firefox OS plugin reference

This article provides a reference showing sample code and examples for many of the Cordova plugins that Firefox OS supports.

Sample App

We have created a sample application (code available on GitHub) to illustrate usage of the device-specific plugins. The images and code snippets in the following sections were taken from the sample app.

image of a sample app with multiple buttons on it.

Plugin reference

Cordova uses a plugin architecture to implement device APIs, such as Accelerometer, Geolocation or Contacts.  These APIs are very similar to Firefox OS Web APIs and Web Activities and are documented on the Cordova website.  Below are the current plugins implemented for Firefox OS and a brief description of how you can include them in your app.  You can always see the current status of plugin development for the Firefox OS Platform by checking Jira on the Apache website.

Notification API

The Notification API is used to alert the user of your app and is implemented in two plugins: org.apache.cordova.dialogs and org.apache.cordova.vibration.  Currently we have implemented the alert, confirm, prompt and vibrate functions.  To use this functionality, add the plugins to your project with the following commands:

cordova plugin add org.apache.cordova.dialogs
cordova plugin add org.apache.cordova.vibration

To get proper styling of popup boxes in Firefox OS, you will need to add the notification.css file to your project.   After adding the dialogs plugin, change to the project/plugins/org.apache.cordova.dialogs/www/firefoxos directory and copy the notification.css file to your project/www/css folder.  Link the CSS file in the <head> element of index.html.

<link rel="stylesheet" type="text/css" href="css/notification.css" />

You can now use the notification functions.

function onPrompt(results) {
    alert("You selected button number " +
          results.buttonIndex +
          " and entered " + results.input1);
}
navigator.notification.vibrate(500);
navigator.notification.prompt(
      'Enter Name', // message
       onPrompt, // callback to invoke
       'Prompt Test', // title
        ['Ok', 'Exit'], // buttonLabels
         'Doe, Jane' // defaultText
);

a simple prompt window asking the user to enter their name.

Compass API

The Compass API is implemented using the org.apache.cordova.device-orientation plugin.  This plugin implements the compass getCurrentHeading and watchHeading functions.  To use it simply run the plugin add command:

cordova plugin add org.apache.cordova.device-orientation

Once the plugin is added, you can use the get and watchHeading functions to get compass information:

function onSuccess(heading) {
    var element = document.getElementById('heading');
    myHeading = (heading.magneticHeading).toFixed(2);
    console.log("My Heading = " + myHeading);
}
function onError(compassError) {
    alert('Compass error: ' + compassError.code);
}
var options = {
    frequency: 500
};
watchID = navigator.compass.watchHeading(onSuccess, onError, options);

phone screen containing a simple compass display.

Accelerometer API

The Accelerometer is accessed using the org.apache.cordova.device-motion plugin and gives the developer access to acceleration data in the x, y and z directions.  This plugin implements the getCurrentAcceleration and watchAcceleration functions. 

To use these functions, add the device-motion plugin to your project by executing the following command.

cordova plugin add org.apache.cordova.device-motion

You can then monitor the acceleration values using code similar to this:

var options = {
    frequency: 100
};
watchIDAccel = navigator.accelerometer.watchAcceleration(onSuccess, onError, options);
function onSuccess(acceleration) {
  var acX = acceleration.x.toFixed(1) * -1;
  var acY = acceleration.y.toFixed(1);
  var acZ = acceleration.z.toFixed(1);
  var vals = document.getElementById('accvals');
  var accelstr = "<strong>Accel X: </strong>" + acX + "<br>" + "<strong>Accel Y: </strong>" + acY + "<br>" + "<strong>Accel Z: </strong>" + acZ;
  vals.innerHTML = accelstr;
}
function onError() {
  alert('Could not Retrieve Accelerometer Data!');
}
</pre>
You can also monitor the device orienttation event and retrieve alpha, beta, and gamma rotation values like:
<pre lang="javascript">
function deviceOrientationEvent(eventData) {
    //skew left and right
    var alpha = Math.round(eventData.alpha);
    //front to back - neg back postive front
    var beta = Math.round(eventData.beta);
    //roll left positive roll right neg
    var gamma = Math.round(eventData.gamma);
    console.log("beta = " + beta + " gamma = " + gamma);
}
window.addEventListener('deviceorientation', deviceOrientationEvent);

image of a phone screen containing a small white ball.

Camera API

The camera API is used to retrieve an image from the gallery or from the device camera.  This API is implemented in the org.apache.cordova.camera plugin.  To use this feature, add the plugin to your project.

cordova plugin add org.apache.cordova.camera

In the Firefox OS implementation of this plugin, the getPicture function will trigger a Web Activity that allows the user to select where the image is retrieved.

Code similar to the following can be used to execute the getPicture() function:

navigator.camera.getPicture(function (src) {
    var img = document.createElement('img');
    img.id = 'slide';
    img.src = src;
  }, function () {}, {
      destinationType: 1
});

Contacts API

The contacts API is used to create or retrieve contacts on the device and is implemented in the org.apache.cordova.contacts plugin.  To access this feature, run the following command:

cordova plugin add org.apache.cordova.contacts

Apps that access contacts must be privileged with the appropriate permission set in the manifest file. For this API, you will need to add the following permissions to the manifest:

"permissions": {
  "contacts": {
    "access": "readwrite",
    "description": "creates contacts"
  }
}

In addition, you will need to change the type of app to privileged in the manifest.

"type": "privileged",

Once the manifest has been changed, you can add contacts with code like the following.

// create a new contact object
var contact = navigator.contacts.create();
var name = new ContactName();
name.givenName = fname;
name.familyName = lname;
contact.name = name;
contact.save(onSuccess, onError);

a simple web form with two text inputs containing a first and last name, and a submit button.

Geolocation API

The geolocation API is used to retrieve the location, time and speed values from the device's GPS unit and is implemented in the org.apache.cordova.geolocation device plugin.

cordova plugin add org.apache.cordova.geolocation

You can retrieve the device latitude, longitude and a timestamp using this API on Firefox OS, but it does require the addition of a permission to the manifest file:

"permissions": {
    "geolocation": {
      "description": "Marking out user location"
    }
}

Adding this permission causes the app to prompt the user for permission to retrieve the GPS data.  You can use either getCurrentPosition() to read the GPS once or watchPosition() to get an interval-based update.

var onSuccess = function (position) {
    console.log('Latitude: ' + position.coords.latitude + '\n' +
    'Longitude: ' + position.coords.longitude + '\n');
};
function onError(error) {
    console.log('Error getting GPS Data');
}
navigator.geolocation.getCurrentPosition(onSuccess, onError);

phone screen containing a black circle indicating location and proximity.
 

Document Tags and Contributors

 Contributors to this page: chrisdavidmills
 Last updated by: chrisdavidmills,