mozilla
Your Search Results

    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,