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.
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
);
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);
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);
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);
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);
